18.2 Migrating Access Gateway Appliance

In migration, you install the latest version of Access Gateway Appliance on a new server, and then migrate the existing data to the new server.

During the migration process, you can provide a new IP address and host name or reuse an existing IP address and host name.

18.2.1 Prerequisites for Migrating Access Gateway Appliance

In addition to the Section 4.2.1, Prerequisites for Installing Access Gateway Appliance, ensure that the following prerequisites are met before migrating Access Gateway Appliance:

  • Upgrade all instances of Administration Console and Identity Server before migration.

  • (If the services are managed by an L4 switch) Remove the device, which needs to be migrated, from the L4 switch. This prevents the L4 switch from sending the user requests to that device during migration.

    Ensure to add the device to the L4 switch after the migration is complete.

  • The upgrade path mentioned in the Release Notes applies to the migration path of Access Gateway Appliance.

    If the version of Access Gateway Appliance is prior to 4.4 Service Pack 4, first upgrade from a supported upgrade path to 4.4 Service Pack 4 using the instructions in Upgrading Access Gateway Appliance in the Access Manager 4.4 Installation and Upgrade Guide.

  • Determine if you want to reuse the existing IP address or a new IP address to setup the system.

  • For using an existing IP address:

    • Take a backup of the following Access Gateway files if these are customized:

      • /opt/novell/nam/mag/conf/server.xml
      • /opt/novell/nam/mag/conf/tomcat.conf
      • /opt/novell/nam/mag/conf/web.xml
      • /opt/novell/nesp/lib/webapp/WEB-INF/web.xml
      • /opt/novell/nam/mag/webapps/nesp/jsp/
      • /opt/novell/nam/mag/webapps/nesp/images/
      • /opt/novell/nam/mag/webapps/agm/WEB-INF/config/current/ErrorPagesConfig.xml
      • /etc/opt/novell/apache2/conf/extra/httpd-multilang-errordoc.conf
      • /opt/novell/apache2/share/apache2/error/include/top.html
      • /opt/novell/apache2/share/apache2/error/include/bottom.html
      • /opt/novell/apache2/share/apache2/error/images/

    • Make a note of the IP address and the host name (with the domain name, such as server.domain.com) of the existing Access Gateway Appliance before migrating to the latest Access Gateway Appliance. The IP address that the existing Access Gateway Appliance uses to communicate with Administration Console will be used for installing the new Access Gateway Appliance.

    • The number of network interfaces along with their values are same for both the new Access Gateway Appliance and the existing Access Gateway Appliance.

  • (For using new IP address) Adding the new Access Gateway Appliance in the existing cluster restores files mentioned in the Settings tab of Code Promotion on Administration Console. If code promotion was performed earlier to get the existing version, a custom file cache is pushed instead of the files mentioned in the Settings tab.

    If you have customized the server.xml and the web.xml files, ensure to take a backup of these files because these files are not restored automatically.

  • You have physical access to the server or server console (in case of VMWare setups) as a root user.

  • The required ports are opened in the firewall. See Setting Up Firewalls.

  • Verify if you have configured any Access Gateway advanced option that refers to a non-default folder in the file system. If yes, you must manually create the folders with the same name before migrating a new Access Gateway Appliance.

    For example, if you have configured the CoreDumpDirectory option as CoreDumpDirectory /data/cores, then before migrating Access Gateway Appliance, create the /data/cores folder.

18.2.2 Upgrading from Access Gateway Appliance 5.0.x

  1. Register to Access Gateway Appliance 5.0 update service on the Common Appliance Framework user interface using https://<IP>:9443 URL. Ignore this step if you have already registered to this service.

    NOTE:For information on registration, see Upgrading the base Operating System and Common Appliance Framework.

  2. Log in to the Access Gateway terminal as a root user.

  3. Run command zypper install nam-ag-channel-meta.

  4. Navigate to the /opt/novell/channel directory.

  5. Run the./upgrade_nam.sh command.

  6. Follow the on-screen prompts to complete the upgrade.

18.2.3 Migrating Access Gateway Appliance

Migrating the existing Access Gateway Appliance to new Access Gateway Appliance does not cause any disruption to the existing setup. You can add new Access Gateway Appliance nodes into the existing Access Gateway Appliance cluster. They can co-exist, but it is recommended to replace all the existing nodes to the latest version.

You can select any one of the following approaches to migrate to Access Gateway Appliance 4.5.x:

Using the Existing IP Address

Workflow:

  1. Back up any files that you have customized and note down the IP address and host name of the existing Access Gateway Appliance.

  2. Shut down the existing Access Gateway Appliance.

  3. Install Access Gateway Appliance with the IP address and host name noted in Step 1.

  4. Restore any customized files from the backup taken earlier.

Use case:

You are upgrading Access Manager 4.4 Service Pack 4 (4.4 SP4) to Access Manager 5.0. After upgrading Administration Console and Identity Server to 5.0 version, you require to migrate Access Gateway Appliance to the 5.0 version using the existing IP address.

It is assumed that your server meets the system requirements mentioned in NetIQ Access Manager System Requirements.

Consider that the setup includes the following components:

  • Access Manager 5.0 Administration Console (primary Administration Console: AC 1)

  • Access Manager 5.0 Identity Server cluster (primary Identity Server: IDP 1 and secondary Identity Server: IDP 2)

  • Access Manager 4.4 SP2 Access Gateway Appliance cluster (primary Access Gateway: AG 1 and secondary Access Gateway: AG 1, AG 2 and A G 3)

Migration process:

  1. If you are first migrating AG 2 using the existing IP address of AG 2, ensure to perform the following actions:

    1. Shut down AG 2

    2. Ensure that Prerequisites for Migrating Access Gateway Appliance are met

  2. Install Access Gateway Appliance (newAGA 2) with the same IP address and hostname as of 4.4 SP2 Access Gateway Appliance (AG 2). For information about installing the new Access Gateway Appliance, see Section 4.2, Installing Access Gateway Appliance.

    After the installation is complete, the configuration sync up takes some time. Do not modify any configuration during this time.

    When the configuration is synced up, the health of this Access Gateway Appliance and the other members of the cluster turn green.

    NOTE:After the installed Access Gateway Appliance turns green, it is recommended to migrate all members of Access Gateway Appliance to Access Gateway Appliance 5.0 before applying the changes by using the update option in Administration Console.

  3. Restore any customized files that you backed up earlier as part of Prerequisites for Migrating Access Gateway Appliance.

    server.xml: If you have modified any elements or attributes in the 4.4 Service Pack 2 environment, the corresponding changes will need to be applied to the server.xml file of the new Access Gateway Appliance.

    Typical changes done to the server.xml in 4.4 SP2 include modifying the 'Address=' attribute to restrict the IP address the application will listen on, or 'maxThreads=' attribute to modify the number of threads.

    In the following example, 4.4 SP2 has customized maxThreads value.

    <Connector port="9029" enableLookups="false" protocol="AJP/1.3" address="127.0.0.1" minSpareThreads="25" maxThreads="300" backlog="0" connectionTimeout="20000", ... ../>

    Make a note of the customizations and merge the changes to the new server.xml file using Advanced File Configurator. For information about how to add or merge files using the Configuration Files page, see Managing Configuration Files in the NetIQ Access Manager 5.0 Administration Guide. After upgrading to 5.0, to restore the customization, you can upload the backup files or make the changes in file and add to Advanced File Configurator to make the changes effective.

    NOTE:Post-Upgrade: To avoid any mismatch of customizations seen on Advanced File Configurator user interface and the file present in the VM server, it is recommended to click the Send Configurations to Servers icon () for all non-temporary files and folders in Access Gateway from the Advanced File Configurator user interface. This action must be performed even if file status is displayed as Configuration sent successfully on the Advanced File Configurator user interface post-upgrade.

  4. Test the Access Gateway Appliance functionality by accessing Access Gateway protected resources and ensuring that pages are rendered successfully.

  5. Repeat Step 1 through Step 4 until you have completely migrated all the existing 4.4 SP2 Access Gateway Appliance (AG 1 and AG 3) to Access Gateway Appliance 5.0.

  6. On the newly added Access Gateway Appliance, restart Tomcat by using the /etc/init.d/novell-mag restart or systemctl restart novell-mag.service command.

Using a New IP Address

Workflow:

  1. Back up any files that you have customized.

  2. Install the new Access Gateway Appliance.

    For information about installing the new Access Gateway Appliance, see Section 4.2, Installing Access Gateway Appliance.

  3. Restore the customized files from the backup taken earlier. For information about how to add or merge files using the Configuration Files page, see Managing Configuration Files in the NetIQ Access Manager 5.0 Administration Guide.

Use case

You are upgrading Access Manager 4.4 SP2 to Access Manager 5.0. After upgrading Administration Console and Identity Server to 5.0 version, you require to migrate Access Gateway Appliance to the 5.0 version using the new IP address.

This scenario assumes that you have a server with the system requirements as mentioned in NetIQ Access Manager System Requirements to install the new Access Gateway Appliance.

Consider that the setup includes the following components:

  • Access Manager 5.0 Administration Console (primary Administration Console: AC 1)

  • Access Manager 5.0 Identity Server cluster (primary Identity Server: IDP 1 and secondary Identity Server: IDP2)

  • Access Manager 4.4 SP2 Access Gateway Appliance cluster (primary Access Gateway: AG 1 and secondary Access Gateway: AG 2).

Migration process:

  1. Determine the primary server in the 4.4 SP2 Access Gateway cluster.

    In this scenario, AG 1 is the primary server. To verify which is the primary server in your set up, perform the following:

    1. Log in to Administration Console.

    2. Click Devices > Access Gateways and select the cluster.

      The primary server is indicated by a red mark beside the IP address.

  2. Install the new Access Gateway Appliance (newAGA 1). See Installing Access Gateway Appliance.

    After the installation, you must configure Access Gateway Appliance to specify the IP address of Administration Console (AC 1), user name, and password in the Administration Console Configuration field on the Appliance Configuration page.

  3. Add the newly installed Access Gateway Appliance to the existing Access Gateway Appliance 4.4 Service Pack 2 cluster.

  4. By default, all proxy services of newly added devices to the cluster listen on the same IP address and port. To configure each reverse proxy service to a specific IP address and port, perform the following steps:

    1. Configure a primary IP Address in YaST for the remaining interfaces.

      1. Go to YaST > Network Devices > Network Settings > Overview.

      2. Select the network card and click Edit.

      3. Specify the IP address.

        Repeat the steps for all the interfaces.

    2. Click Devices > Access Gateways, and select the device.

    3. Click New IP > OK.

    4. Add the secondary IP address, if applicable, to the interfaces from Network Settings > Adapter List.

    5. Configure the DNS in Network Settings > DNS.

    6. Add the Host entries (if any) in Network Settings > Hosts.

    7. Set up the routing (if any) in Network Settings > Gateways.

    8. Under Services, click Reverse Proxy/Authentication. In the Reverse Proxy List, click the proxy service name. Select the newly added cluster member and select the listening IP address for that service.

      (Optional) If you want to specify the outbound connection to the web server, click Web Servers > TCP Connect Options. Select the Cluster Member and select the IP address from the list against Make Outbound Connection Using if you want to select the outbound IP address to communicate with the web server.

    9. Restore any customized files that you backed up earlier as part of Prerequisites for Migrating Access Gateway Appliance.

      The files mentioned in Administration Console at <username> > Code Promotion > Settings get restored automatically:

      Copy the content of the server.xml file to the corresponding file in the new location.

      Typical changes done to the server.xml in 4.4 SP2 include modifying the 'Address=' attribute to restrict the IP address the application will listen on, or 'maxThreads=' attribute to modify the number of threads.

      server.xml: If you have modified any elements or attributes in the 4.4 SP2 environment, apply the corresponding changes the server.xml file of the new Access Gateway Appliance.

      In the following example, 4.4 SP2 contains maxThreads value.

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

      Make a note of the customizations and merge the changed values in the new server.xml file. For information about how to add or merge files using the Configuration Files page, see Managing Configuration Files in the NetIQ Access Manager 5.0 Administration Guide.

  5. Test the Access Gateway Appliance functionality by accessing Access Gateway protected resources and ensuring that the pages are rendered successfully.

  6. On the Administration Console, specify AGA 1 as the primary server and click Update.

  7. Remove 4.4 SP2 Access Gateway Appliance (AG 1) from the cluster.

  8. Install new Access Gateway Appliance (AGA 2) as in Step 2 and add it to the 4.4 SP2 Access Gateway Appliance cluster as in Step 3.

  9. After you confirm that all the services are running remove 4.4 SP2 Access Gateway Appliance (AG 2) from the cluster.

  10. Click OK > Update all.

  11. Repeat Step 2 to Step 5 until you migrate all existing Access Gateway Appliance from 4.4 Service Pack 2 to 5.0.

    After installing Access Gateway Appliance, delete all 4.4 SP2 Access Gateway Appliances from Administration Console.

  12. On the newly added Access Gateway server, restart Tomcat by using the /etc/init.d/novell-mag restart or systemctl restart novell-mag.service command.