Chapter 12. Upgrading from a Release Prior to NQE 3.1


Note: If you are upgrading from a UNICOS 9.0 system that has NQS and FTA software bundled in your operating system and are upgrading to the NQE 3.1 release, follow the steps in this section.


If you are upgrading to NQE 3.3 from a release prior to the NQE 3.1 release, follow the procedures in this chapter after you have installed NQE.

If you are upgrading to NQE 3.3 directly from the NQE 3.1 release, follow the steps listed in Chapter 5, “Upgrading Directly from NQE 3.2 to NQE 3.3”.


Warning: If you have jobs that are running or suspended, they can be preserved only across an upgrade on UNICOS systems. If possible, jobs that are running or suspended should be allowed to finish before you upgrade NQE on UNICOS systems, and these jobs must be allowed to finish before upgrading on all other platforms. Jobs that are queued are preserved across an upgrade on all platforms.



Warning: It is strongly recommended that you do not modify the NQE_NQS_SPOOL nqeinfo file variable. If you choose to modify this variable, you must also ensure that the NQS log file path is correctly set by using the qmgr(8) command. Failure to do so may result in NQS log messages not being logged.



Note: To upgrade NQE, you must have root permission.



Note: For UNICOS systems, as of the NQE 3.1 release, the user and administrative commands for NQE, NQS, and FTA are now in /nqebase/bin and /nqebase/etc.

The steps in the rest of this chapter should be performed after NQE 3.3 is installed, but before you set NQE 3.3 to be the default version (by using the nqemaint(8) command), or use the NQE configuration utility (nqeconfig(8) command), or start NQE.

Also, you should read Chapter 14, “Read This Before You Start NQE”, for important information that you should know about before you start NQE 3.3.

Upgrading from NQE 3.0

Because new NQE configuration variables were added in the NQE 3.3 release, use the default nqeinfo file that is provided with the NQE 3.3 release. Compare your NQE 3.0 nqeinfo file with the default NQE 3.3 nqeinfo file, and modify the NQE 3.3 nqeinfo file as needed by using the NQE configuration utility (nqeconfig(8)). Do not use your NQE 3.0 nqeinfo file as direct input into NQE 3.3. (For information about how to use the NQE configuration utility, see Appendix B, “Configuring NQE Variables”.)

No upgrade steps are required to upgrade from NQE 3.0 to NQE 3.3. To set NQE 3.3 to be the default NQE version, to prepare a node to run NQE 3.3, and to configure NQE variables, see the following:

For information about how to start and stop NQE, see the nqeinit(8) and nqestop(8) man pages.

Upgrading from NQE 2.0

The procedures described in this section are required to upgrade NQE 2.0 NQE server nodes and clients:

For clients and NQE server nodes, see the following:

For information about how to start and stop NQE, see the nqeinit(8) and nqestop(8) man pages.


Note: Steps 1 and 2 should be performed before you have stopped NQE 2.0.


Procedure 12-1.

  1. Create a directory to hold files related to the current NQE 2.0 system by entering the following command:

    mkdir backup_directory

  2. Save the NQE 2.0 NLB configuration by using the following commands; these commands save the NQE 2.0 name map, the NQE 2.0 ACLs, and the NQE 2.0 FTA configuration:

    /nqebase/bin/nlbconfig -mdump -f backup_directory/old_name_map
    /nqebase/bin/nlbconfig -adump -f backup_directory/old_acl
    /nqebase/bin/nlbconfig -odump -t FTA_CONFIG \
       -f backup_directory/old_fta_config
    /nqebase/bin/nlbconfig -odump -t FTA_DOMAIN \
       -f backup_directory/old_fta_domain

    These files will be used in steps 8, 9, and 10 if local modifications were made to your NQE 2.0 NLB name map, the acl file, or the FTA configuration.

  3. Stop NQE 2.0 by executing the following command:

    /nqebase/etc/nqestop

  4. Move the NQE 2.0 NLB configuration from the NQE spool directory, by using the following command:

    mv NLB_SERVER_DIR backup_directory

    The NLB_SERVER_DIR setting is provided in your /etc/nqeinfo file.

    Moving this directory forces the creation of a new NLB_SERVER_DIR that has the default NQE 3.3 NLB configuration when NQE 3.3 is first initialized.

  5. Because new NQE configuration variables were added in the NQE 3.3 release, use the default nqeinfo file that is provided with the NQE 3.3 release. Compare your NQE 2.0 nqeinfo file with the default NQE 3.3 nqeinfo file, and modify the NQE 3.3 nqeinfo file as needed by using the NQE configuration utility (nqeconfig(8)). Do not use your NQE 2.0 nqeinfo file as direct input into NQE 3.3. (For information about how to use the NQE configuration utility, see Appendix B, “Configuring NQE Variables”.)

  6. Configure NQE as documented in the following:

  7. NQE 3.3 is now your default version. Start NQE 3.3 by entering the following command:

    /nqebase/etc/nqeinit

    This step loads the new NLB_SERVER_DIR, which has the NQE 3.3 NLB default configuration.

  8. If you have changed the ACL permissions in NQE 2.0, you must make the changes again for NQE 3.3. To determine whether you will need to make changes to the master ACL and default ACL, compare the file config in the NQE 3.3 NLB_SERVER_DIR with the copy of the NQE 2.0 file config in your backup copy of the NQE 2.0 NLB_SERVER_DIR that you made in step 4 above.

    To determine whether you need to make changes to other ACLs, use the following command to obtain the default NQE 3.3 ACL configuration:

    /nqebase/bin/nlbconfig -adump -f backup_directory/acl

    Compare the content of this file with the content of the old_acl file created by step 2 above.

    For more information about changing ACLs, see Overview of NLB configuration and Configuring name maps, objects and ACLs in NQE Administration, publication SG-2150.

  9. If you have changed the FTA configuration in your NQE 2.0 system, you must make the changes again for NQE 3.3.

    You can use the following commands to obtain the default NQE 3.3 FTA configuration:

    /nqebase/bin/nlbconfig -odump -t FTA_CONFIG \
       -f backup_directory/fta_config
      /nqebase/bin/nlbconfig -odump -t FTA_DOMAIN \
       -f backup_directory/fta_domain

    Compare the content of these files with the content of the files old_fta_config and old_fta_domain that were created in step 2 above to determine what changes you must make. For additional information on configuring FTA, see FTA Administration in NQE Administration, publication SG-2150.

  10. If you have made changes to your NLB name map for NQE 2.0, you must make the changes again for NQE 3.3.

    Because significant changes were made to the NLB name map in the NQE 3.0 release, it will not be useful to compare your modified NQE 2.0 name map to the NQE 3.3 name map. In your NQE 2.0 directories, you can find the default NQE name map in /nqebase/2.0/etc/name_map. Compare this NQE 2.0 default file with the NQE 2.0 file old_name_map that was created in step 2 above to determine what changes you must make. For additional information on configuring the name map, see Configuring name maps, objects and ACLs in NQE Administration, publication SG-2150.

  11. If you have changed the NLB policies in NQE 2.0, you must reload your policies file. The current policy file is kept in NLB_SERVER_DIR/policies. In step 4 above, you moved the NQE 2.0 NLB_SERVER_DIR to backup_directory. You can compare your NQE 2.0 policies file from the backup location and use it to help you determine whether you need to change the NQE 3.3 default policies file in NLB_SERVER_DIR.

    After you have modified the policies file, issue the following command to request that the NLB server reread the policies file:

    /nqebase/bin/nlbconfig -pol

    For further information on NLB policies, see NLB Administration and Implementing NLB policies in NQE Administration, publication SG-2150.

  12. When you are finished with the conversion from the NQE 2.0 NLB configuration, you may remove the backup_directory.

Upgrading to NQE 3.3 If Running UNICOS 9.0 version of NQE, UNICOS 9.0 NQS/FTA (No NQX License)

The following steps apply to upgrades for full NQE 3.3 functionality and for the NQE 3.3 UNICOS subset (NQS and FTA components only).

Procedure 12-2.

  1. Create a directory to hold files related to the current UNICOS system:

    mkdir backup_directory

  2. If your site uses NQS user exits, see Section 5.25.1, “NQS user exits for UNICOS and UNICOS/mk systems,” in NQE Administration, publication SG-2150. Your current directory must be /nqebase/${NQE_VERSION} when you rebuild NQS.

  3. For NLB server nodes, if local modifications were made to the NLB name map or ACLs, save the current NLB configuration by using the following commands:

    /usr/bin/nlbconfig -mdump -f backup_directory/old_name_map
    /usr/bin/nlbconfig -adump -f backup_directory/old_acl

  4. Save the current NQS configuration by using the following commands, starting the current NQS if it is not running.


    Note: If you want to save the original NQE 3.3 nqs_config file, you must rename it.


    /usr/bin/qstart -i /dev/null
    /usr/bin/qmgr
    > snap file = /nqebase/${NQE_VERSION}/etc/nqs_config
    > exit 

  5. Edit the snap file to make the following changes, or use the ksh script in /nqebase/${NQE_VERSION}/examples/remabspath.

    • Change all pipe_queue server path names from absolute path names to pipeclient:

      create pipe_queue nqenlb priority=63 server=(pipeclient CRI_DS)
      create pipe_queue gate priority=63 server=(pipeclient)

    • Change all absolute path name references for netdaemon, netserver, and netclient:

      set network client=(netclient)
      set network daemon=(netdaemon)
      set network server=(netserver)


    Note: Do not change the checkpoint directory path name if there are restart files within the directory.


  6. If you want to preserve existing NQS requests and FTA queued transfers, see “Migrating NQS/FTA Requests”.

  7. If you have not yet shut down NQE/NQS, do so by using the following commands:

    /etc/nqestop (if you have an NQE (NQX) license)
    /etc/qstop (if you are running the NQS/FTA subset only)

  8. Because new NQE configuration variables were added in the NQE 3.3 release, use the default nqeinfo file that is provided with the NQE 3.3 release. Compare your NQE nqeinfo file with the default NQE 3.3 nqeinfo file, and modify the NQE 3.3 nqeinfo file as needed by using the NQE configuration utility (nqeconfig(8)). Do not use your previous NQE nqeinfo file as direct input into NQE 3.3. (For information about how to use the NQE configuration utility, see Appendix B, “Configuring NQE Variables”.)

  9. Use the NQE maintenance utility (nqemaint(8)) to set the NQE 3.3 release to be the default NQE version.

  10. Configure NQE as documented in the following:


    Warning: You currently have two sets of commands and databases for both NQS and FTA. It is very easy to mix and mismatch these commands and databases; however, mixing of these sets is not supported. Be sure that /nqebase/bin:/nqebase/etc precedes /etc:/usr/bin in your path, or use the full path name for NQE commands, as shown in this chapter. Ensure that your NQEINFOFILE environment variable is either not set or is pointing to /etc/nqeinfo.


  11. If you have saved your NQS and/or FTA database files, go to “Restoring NQS/FTA Database Files”, and follow the directions in that section. Otherwise, continue the procedure by starting NQE 3.3 with one of the following commands:

    /nqebase/etc/nqeinit (if you have an NQE 3.3 license)
    /nqebase/etc/qstart (if you are running the NQS/FTA subset only) 

  12. If you have routed NQS requests to another NQS server, route them back as described in “Routing Back NQS Jobs That Were Stored on Another NQS Server”.

  13. If your site has local modifications to the NLB configuration, the files created in step 3 can be used as examples to recreate these modifications within the NQE 3.3 NLB configuration. These files, however, cannot be used directly as input to the /nqebase/bin/nlbconfig command.

    For more information on configuring the NLB, see the following information in NQE Administration, publication SG-2150:

    • Configuring name maps, objects, and ACLs

    • Changing ACL permissions

    • Example of writing a load-balancing policy

  14. If you have jobs that are checkpointed, let these jobs restart. When they have all been restarted, you should change the checkpoint directory by entering the following commands:

    # /nqebase/bin/qmgr
    Qmgr: SET CHeckpoint_directory /usr/spool/nqe/spool/
            private/root/chkpnt
    Qmgr: quit
    #

  15. If you start or stop NQS or NQE in the /etc/config/daemons file, change the entries to the following:

    /nqebase/etc/nqeinit (if you have an NQE 3.3 license)
    /nqebase/etc/nqestop (if you have an NQE 3.3 license)
    
    /nqebase/etc/qstart (if you are running the NQS/FTA subset only)
    /nqebase/etc/qstop (if you are running the NQS/FTA subset only)

  16. If you are running full NQE, in order to use the sdaemon(8) command to start or stop NQE, you must comment out the NQS line in the /etc/config/daemons file, and add a line for NQE.

  17. If applicable, remove the conversion files from the backup directory by using the following commands:

    cd backup_directory
    rm qstat-a qstat-f nqs_cpio fta_cpio 

Migrating NQS/FTA Requests

The information in this section provides a way to migrate NQS queued job requests and FTA queued file transfers to the new NQE 3.3 spool area. If the NQS jobs have a restart file, the jobs will be restarted under NQE 3.3.

The following are some suggested methods of preserving NQS batch requests across an NQE 3.3 upgrade:

The following sections describe these methods.

Empty NQS Queues

To empty the NQS queues, use the following procedure:

Procedure 12-3.

  1. To stop new requests from entering the queues, disable all the NQS queues.

  2. Let the requests that are currently in the queues complete execution.

  3. When there are no requests remaining in the queues, shut down NQS.

  4. When all queues are empty, complete the upgrade to NQE 3.3 by going back to step 7 of “Upgrading to NQE 3.3 If Running UNICOS 9.0 version of NQE, UNICOS 9.0 NQS/FTA (No NQX License)”.

Route NQS Jobs to Another NQS Server

You can route the queued batch requests to another NQS server so that they can be preserved during the NQE upgrade.


Note: This method does not work for batch requests that are submitted from stations through USCP.

The user and group IDs must be the same on both hosts. The users must have the appropriate .nqshosts or .rhosts file set up on both hosts, or the jobs will be deleted.

Use the following procedure to route the queued batch requests to another NQS server:

Procedure 12-4.

  1. Set up a pipe queue on the upgrading UNICOS system. The pipe queue should have an enabled, stopped pipe queue as its destination at the host storing the requests.

  2. Move all queued batch requests on the upgrading UNICOS system to the pipe queue.

  3. Running requests cannot be moved to a pipe queue. To move a request that is currently running, stop the corresponding batch queue and rerun the request by using the qmgr rerun command. This action returns the request to a queued state, from which it can be moved to a pipe queue. Some batch requests may be specified as nonrerunnable, and you must let them complete.

  4. When all the requests have been moved to the storing machine and the NQS queues are empty, complete the upgrade to NQE 3.3 by going back to step 7 of “Upgrading to NQE 3.3 If Running UNICOS 9.0 version of NQE, UNICOS 9.0 NQS/FTA (No NQX License)”.

Save the NQS/FTA Database Files

Because each site has its own requirements, it is not possible to describe all the conditions that a site may encounter (such as local mods and file system setup). If the solutions described in either “Empty NQS Queues” or “Route NQS Jobs to Another NQS Server” meet your site's needs, you are encouraged to use them instead of the following procedure because they are easier to use and are less dependent on local configurations.

The following steps should be performed before you use the nqemaint(8) or nqeconfig(8) command. You should perform all actions with root permission.

Procedure 12-5.

  1. Create a directory to hold files related to the current versions of NQS and FTA that are running under NQE 1.1, UNICOS 9.0 by entering the following command:

    mkdir backup_directory

  2. Shut down NQE/NQS by using one of the following commands:

    /nqebase/etc/nqestop (if you have an NQE 3.3 license)
    /nqebase/etc/qstop (if you are running the NQS/FTA subset only)

  3. Save a copy of the current status of the NQS queues and requests as follows:

    /usr/bin/qstat -f > backup_directory/qstat-f
    /usr/bin/qstat -a > backup_directory/qstat-a

  4. Preserve the current NQS requests for migration to the new NQE 3.3 spool. Use the following command to save the required NQS database files from the current NQS spool:

    /nqebase/${NQE_VERSION}/etc/qdump backup_directory/nqs_cpio

  5. Preserve the current FTA queued file transfers by using the following commands (NQE_FTA_QUEUE is defined in /etc/nqeinfo):

    cd NQE_FTA_QUEUE
    ls qf* | cpio -om > backup_directory/fta_cpio

Restoring NQS/FTA Requests


Warning: You currently have two sets of commands and databases for both NQS and FTA. Ensure that your NQEINFOFILE environment variable is either not set or is pointing to /etc/nqeinfo. Also, ensure that /nqebase/bin:/nqebase/etc precedes /etc:/usr/bin in your path, or use the full path name for NQE commands, as shown.

This section describes how you can restore the NQS and FTA requests that you saved when you followed the method described in “Route NQS Jobs to Another NQS Server” or in “Save the NQS/FTA Database Files”.

Routing Back NQS Jobs That Were Stored on Another NQS Server

If you routed jobs to another NQS server, route the requests at the remote host back to the upgraded host once NQE 3.3 is running and configured. You can do this by creating a pipe queue on the remote host with a destination queue on the upgraded server. Then, move the requests to this queue.

If you restored NQS following this method, complete the upgrade procedure by going back to step 13 of “Upgrading to NQE 3.3 If Running UNICOS 9.0 version of NQE, UNICOS 9.0 NQS/FTA (No NQX License)”; otherwise, see “Restoring NQS/FTA Database Files”.

Restoring NQS/FTA Database Files

If you saved the NQS and FTA database files as described in “Save the NQS/FTA Database Files”, you can use the following steps to restore them.

Procedure 12-6.

  1. Start NQE 3.3 to create the 3.3 spool directories and recreate the NQS queues from the modified snap file you placed in /nqebase/${NQE_VERSION}/etc/nqs_config by using one of the following commands:

    /nqebase/etc/nqeinit (if you have an NQE 3.3 license)
    /nqebase/etc/qstart (if you are running the NQS/FTA subset only) 

  2. List the NQE 3.3 NQS queues with the following command. Compare this list with the list of queues from UNICOS 9.0 in the backup_directory/qstat-f file.

    /nqebase/bin/qstat -f 


    Warning: The NQE 3.3 NQS queue configuration must be identical to your previous UNICOS 9.0 NQS configuration.

    NQS checks several dependencies when it rebuilds queues. If there are errors or inconsistencies found in a request, NQS deletes it. When NQS scans requests to rebuild its queues, there must be a control file and a data file. The request must reference an existing queue name, and a valid transaction entry that describes the state of the job must be present in the transact file.


  3. Shut down NQE 3.3 before you reload the NQS and FTA requests by using one of the following commands:

    /nqebase/etc/nqestop (if you have an NQE 3.3 license)
    /nqebase/etc/qstop (if you are running the NQS/FTA subset only) 

  4. Restore the NQS database files, which were saved from the previous qdump operation, by using the following command:

    /nqebase/etc/qload backup_directory/nqs_cpio

  5. Restore the FTA queued file transfers by entering the following commands:

    cd NQE_FTA_QUEUE
    cpio -imu < backup_directory/fta_cpio

  6. Restart NQE 3.3 by entering the following command:

    /nqebase/etc/nqeinit -i /dev/null
        (if you have an NQE 3.3 license)
    /nqebase/etc/qstart -i /dev/null
        (if you are running the NQS/FTA subset only)

  7. List the NQE 3.3 queued NQS requests as follows. Compare this with the list of requests from UNICOS 9.0 stored in the backup_directory/qstat-a file, to ensure that all requests have been reloaded.

    /nqebase/bin/qstat -a 

    If these procedures are successful, your batch requests will now be in the new spool area. If you have no jobs that are checkpointed, you can delete the old spool area, which is /usr/spool/nqs by default. If you have checkpointed jobs, you should wait for these checkpointed jobs to restart before you delete the old spool area.

  8. Start all queues by using the following commands:

    /nqebase/bin/qmgr
    Qmgr: start all_queues

If you restored NQS following this method, complete the upgrade procedure by going back to step 13 of “Upgrading to NQE 3.3 If Running UNICOS 9.0 version of NQE, UNICOS 9.0 NQS/FTA (No NQX License)”; otherwise, see “Routing Back NQS Jobs That Were Stored on Another NQS Server”.