Migrate to CentOS Virtual Appliance

This topic describes how to recreate your environment from a current v8.x or higher RHEL-based gateway Virtual Appliance to a CentOS-based Virtual Appliance.
gateway94
This topic describes how to recreate your environment from a current v8.x or higher RHEL-based 
Layer7 API Gateway
 Virtual Appliance to a CentOS-based Virtual Appliance.
Contents:
 
 
 (1) The migration progress is intended for Gateway administrators or other advanced technical users familiar with the Gateway system files. (2) The commands described in this topic must be executed from a privileged shell. (3) The source and target Gateways must be the same version, including CR releases. For example, if the source Gateway is running CR2, the target Gateway cannot be on CR1.
Steps to Perform on the Source Gateway
  1. Ensure that the source Gateway is running version 9.1 at a minimum.
  2. Create and edit the following file:
    1. Create this file:
       /home/ssgconfig/CentOS_migration_fileList.txt
       
    2. Copy and paste the following list of files to 
      CentOS_migration_fileList.txt
       at a minimum. If you have customized the stock Gateway image in any way, append any custom files as necessary. (Contact your system administrator if unsure.)
      /etc/hosts
      /etc/iproute2/rt_tables
      /etc/ldap.conf
      /etc/localtime
      /etc/motd
      /etc/nsswitch.conf
      /etc/ntp.conf
      /etc/ntp/keys
      /etc/ntp/step-tickers
      /etc/openldap/ldap.conf
      /etc/pam.d/login
      /etc/pam.d/sshd
      /etc/pam.d/system-auth-ac
      /etc/pam_radius.conf
      /etc/rc.local
      /etc/resolv.conf
      /etc/rsyslog.conf
      /etc/skel_ssg/.bash_logout
      /etc/skel_ssg/.bash_profile
      /etc/skel_ssg/.bashrc
      /etc/snmp/snmpd.conf
      /etc/ssh/ssh_allowed_users
      /etc/ssh/sshd_config
      /etc/sudoers
      /etc/sysconfig/authconfig
      /etc/sysconfig/clock
      /etc/sysconfig/i18n
      /etc/sysconfig/iptables
      /etc/sysconfig/keyboard
      /opt/SecureSpan/Gateway/config/backup/cfg/backup_manifest
      /opt/SecureSpan/Gateway/node/default/etc/conf/node.properties
      /opt/SecureSpan/Gateway/node/default/etc/conf/omp.dat
      /opt/SecureSpan/Gateway/node/default/etc/conf/ssglog.properties
      /opt/SecureSpan/Gateway/node/default/etc/conf/system.properties
      /opt/SecureSpan/Gateway/node/default/etc/conf/trusted_signers
  3. If the target Gateway has the same network settings as the source Gateway, also append these files to the list:
    /etc/sysconfig/network
    /etc/sysconfig/network-scripts/ifcfg-eth0
    /etc/sysconfig/network-scripts/ifcfg-eth1
    /etc/sysconfig/network-scripts/ifcfg-eth2
    /etc/sysconfig/network-scripts/ifcfg-eth3
    /etc/sysconfig/network-scripts/route-eth0
    /etc/sysconfig/network-scripts/route-eth1
    /etc/sysconfig/network-scripts/route-eth2
    /etc/sysconfig/network-scripts/route-eth3
    /etc/sysconfig/network-scripts/rule-eth0
    /etc/sysconfig/network-scripts/rule-eth1
    /etc/sysconfig/network-scripts/rule-eth2
    /etc/sysconfig/static-routes
    This ensures that the network settings, routing rules, etc., are migrated.
  4. Stop the Gateway and Enterprise Service Manager (if present):
    1. Run the command:
      # service ssg stop
      # service esm stop
      (if Enterprise Service Manager present)
  5. Run this command to create a tarball file and change its ownership:
    # tar --acls -czvf /home/ssgconfig/migration_files.tar.gz -T /home/ssgconfig/CentOS_migration_fileList.txt
    # chown ssgconfig.ssgconfig /home/ssgconfig/migration_files.tar.gz
    where 
    CentOS_migration_fileList.txt
     is the text file created in step 2 that lists the files being migrated.
     You can normally ignore any "missing files" messages; not all files are present in every installation of the Gateway. The tarball is still created and the missing files are ignored. However, if any file that you manually added in step 2 is identified as missing, verify that the full path is provided.
  6. Perform a custom backup on the source Gateway as follows:
    1. Make note of the current permissions for the following files:
      # /etc/snmp/snmpd.conf
      # /etc/pam_radius.conf
      # /etc/sudoers
    2. Change the permissions of the files:
      # chmod a+r /etc/snmp/snmpd.conf
      # chmod 604 /etc/pam_radius.conf
      # chmod 444 /etc/sudoers
    3. Run the following commands:
      # /opt/SecureSpan/Gateway/config/backup/ssgbackup.sh -image /tmp/gateway.zip -maindb -audits -ca -ext -ma
      # mv /tmp/*gateway.zip /home/ssgconfig
      # chown ssgconfig.ssgconfig /home/ssgconfig/*gateway.zip
      These commands do the following:
      1. Backs up the Gateway.
      2. Moves the backup to the 
        /home/ssgconfig
         directory.
      3. Changes the ownership of the backup file.
      For more information on backups, see "Performing a Custom Backup" in Back Up Gateways. 
       Do not include either the "-os" or "-config" options in the custom backup. The OS and Gateway configuration files are migrated in the tarball file.
    4. Restore the permissions of the files, as noted in step (a):
      # /etc/snmp/snmpd.conf # /etc/pam_radius.conf # /etc/sudoers
  7. Use 
    scp
     or 
    sftp
     to copy 
    <date_timestamp>_gateway.zip
     and 
    migration_files.tar.gz
     from the 
    /home/ssgconfig
     directory to an intermediate system (for example, a workstation). These files are copied to the target Gateway later.
  8. Shut down the source Gateway virtual machine.
Steps to Perform on the Target Gateway
  1. Ensure that the target Gateway is running the same version as the source Gateway.
  2. Start up a new virtual appliance using the CentOS .ova file. For information on how to do this, refer to the 
    CA API Gateway Virtual Appliance Getting Started
    , under "CA API Management Technical Documentation" in Release Notes.
  3. Set up networking on the target Gateway.
    • If the target Gateway shares the same network configuration as the source, then configure the eth0 interface to allow 
      scp
       and 
      sftp
       access for copying the files. Additional steps will be configured when the tarball is extracted. 
      Tip:
       If you added the network configuration files to 
      CentOS_migration_fileList.txt
       as described in step 3 under "Steps to Perform on the Source Gateway", then the target Gateway shares the same configuration.
      1. From the Gateway main menu, select option 
        1
         (Configure system settings).
      2. Select option 
        1
         (Configure Networking and System Time Settings).
      3. Complete the prompts in the configurator 
        for eth0 only. Other interfaces are configured when the tarball is extracted.
         For more information, see Option 1 - Configure Networking and System Time Settings.
    • If the target Gateway has a different network configuration, then complete the entire configuration with the new settings:
      1. From the Gateway main menu, select option 
        1
         (Configure system settings).
      2. Select option 
        1
         (Configure Networking and System Time Settings).
      3. Complete the prompts in the configurator. For more information, see Option 1 - Configure Networking and System Time Settings.
  4. Use 
    scp
     or 
    sftp
     to copy the 
    <date_timestamp>_gateway.zip
     and 
    migration_files.tar.gz
     to the 
    /home/ssgconfig
     folder on the target Gateway
  5. Access the privileged shell and run the following command as the root user to extract the 
    .tar.gz
     migration file:
    # tar --acls -xvf /home/ssgconfig/migration_files.tar.gz -C /
    If the network configuration of the target Gateway is the same as the source Gateway, run the following commands to update the configuration to recognize the new hardware:
    # IFS='
    '
    # for MAC in `ifconfig -a | grep '^eth' | sed 's/ *Link.*HWaddr//'` ; do sed -i "s/HWADDR=.*/HWADDR=${MAC#* }/" /etc/sysconfig/network-scripts/ifcfg-${MAC%% *} ; done
    Reboot the Gateway appliance to implement the new settings:
    # reboot
  6. Access the privileged shell and restore the Gateway on the target:
    # mv /home/ssgconfig/
    <date_timestamp>
    _gateway.zip /tmp
    # chown layer7.layer7 /tmp/
    <date_timestamp>
    _gateway.zip
    # service ssg stop
    # /opt/SecureSpan/Gateway/config/backup/ssgrestore.sh -image /tmp/
    <date_timestamp>
    _gateway.zip -dbu root -dbp
    <password>
    For more information about restoring, see Restore Gateways 
  7. If the source Gateway used either IP or FQDN to access the database, configure the target Gateway to use the correct IP or FQDN:
    1. Access the Gateway main menu and then select option 
      2
       (Display CA API Gateway configuration menu).
    2. Select option 
      3
       (Configure the CA API Gateway) and then option 
      1
       (Reconfigure the database connection).
    3. Complete the prompts in the configurator. For more information, see Gateway Configuration Menu (Appliance).
  8. Reboot the Gateway:
    1. Access the Gateway main menu.
    2. Select option 
      R
       (Reboot the CA API Gateway appliance (apply the new configuration)).
  9. Verify that the migrated Gateway is working as expected. If you have any customizations (for example, backup systems, monitoring), reapply them now.
Frequently Asked Questions
Question
Answer
What about databases other than the local Gateway database?
Other databases (such as the OAuth Toolkit db) are not included in the migration described here. Migrate these separately.
What happened to my MySQL grants?
Manually reapply the MySQL grants on the target Gateway using these commands:
mysql> SHOW GRANTS FOR 'root';
mysql> GRANT ALL PRIVILEGES ON . TO 'root'@'%' IDENTIFIED BY '
<password>
' WITH GRANT OPTION;
The first command displays the existing grants for the root users.
The second command grants the privileges. Modify as necessary to suit your needs. Note that 
"<password>"
 is the password for the user.
I'm having problems with my restored Gateway.
Visit the Troubleshoot: Problems and Solutions section for help. If you require further assistance, contact CA Support.
I'm having problems with my JMS Destinations after migration.
This is caused by file permissions. Add the read permission for the JMS client libraries installed and then restart the Gateway.
I have issues with my Enterprise Service Manager after migration.
Reconfigure the Enterprise Service Manager on the target Gateway. For more information, see "Configure the Enterprise Service Manager" in the Enterprise Service Manager online documentation.