Migrating an administrative agent profile and its registered set of managed base application servers

Administrative agent profiles manage multiple base application servers in environments such as development, unit test or that portion of a server farm that resides on a single machine. Before you can migrate managed base application servers from Version 7.0 or later to Version 9.0, you must first migrate the administrative agent.

Before you begin

Supported configurations:

This topic is about profile configuration migration. To migrate your applications to the latest version, use the WebSphere® Application Server Migration Toolkit.

Review the migration planning information. See Knowledge Collection: Migration planning for WebSphere Application Server.

Tip: Rather than specifying individual parameters on migration commands, you can specify the -properties file_name.properties parameter to input a properties file. For more information, see Defining your migration through properties.

About this task

A base application server becomes managed when it is registered with a single administrative agent. An administrative agent may manage one or more base application servers and must be at the same release level and on the same machine as the base application servers it is managing. Because of this restriction, the administrative agents on both the old and new release run simultaneously until all managed base application servers are migrated. The migration of an administrative agent does not bring forward its old port values, however, all other configuration data is migrated.

Access the Version 9.0 admin agent console using the WC_ adminhost or WC_ adminhost_ secure ports as defined in the new Version 9.0 admin agent's serverindex.xml file. Additionally, the Version 7.0 or later administrative agent must not be shut down or disabled during this procedure.

For migrating the managed base application server in a flexible management environment, ensure that the node names are the same on Version 9.0 and previous releases.

Avoid trouble: Ensure that your setting for the maximum number of open files is 10000 or greater. If the number of open files is too low, this can cause a variety of migration failures.

Procedure

Install WebSphere Application Server Version 9.0 onto the target host in a new directory.

For more information, see the installation documentation.

Create a Version 9.0 administrative agent profile that will be the target of the administrative agent migration.

Run the manageprofiles command with the appropriate parameters to create a new administrative agent profile.

For example:

C:\WebSphere\AppServer90\bin>manageprofiles.bat -create -profileName 90AdminAgent01 -profilePath 
C:\WebSphere\AppServer90\profiles\AdminAgent01 -templatePath C:\WebSphere\AppServer90\profileTemplates\management 
-serverType ADMIN_AGENT -nodeName AdminAgentNode01 -cellName AdminAgentCell01 -hostName mydmgrhost.company.com

Ensure that all in-progress jobs are completed on the managed profiles.
Stop polling the job manager on profiles that are getting jobs from the job manager.

Before you start polling for jobs, complete WASPreUpgrade and WASPostUpgrade for the managed profile. For more information, see ManagedNodeAgent command group for the AdminTask object using wsadmin scripting.
Save the current administrative agent configuration to the migration backup directory by running the WASPreUpgrade command from the new WebSphere Application Server installation root bin directory.

The WASPreUpgrade command does not make any changes to the old configuration.
1. Run the WASPreUpgrade command, specifying the migration backup directory and the Version 7.0 or later installation root directory.
  
  For information about command parameters, see WASPreUpgrade command.
  For example:
```
C:\WebSphere\AppServer90\bin>WASPreUpgrade.bat C:\WAS70AdminAgentbackup C:\WebSphere\AppServer70 -oldProfile 70AdminAgent01 
-traceString *=all=enabled -tracefile C:\WAS70AdminAgentbackup\logs\WASPreMigrationSummary.log
```
2. Review warnings or errors in the console output and WASPreUpgrade logs.
  After the WASPreUpgrade command is complete, check the console output for Failed with errors or Completed with warnings messages. Then, check the following log files for any warnings or errors:
  - migration_backup_dir/logs/WASPreMigrationSummary.log
  - WASPreUpgrade.timestamp.log
  - WASPreUpgrade.trace
  If there are errors, fix the errors and run the WASPreUpgrade command again. Check whether the warnings affect any other migration or runtime activities on Version 9.0.
  
  If the command completed successfully, it is not necessary to check the logs for errors or warnings.
Restore the previous administrative agent configuration by running the WASPostUpgrade command from the new WebSphere Application Server install root bin directory.
1. Run the WASPostUpgrade command to restore the saved administrative agent configuration into the new Version 9.0 administrative agent profile.
  For example:
```
C:\IBM\WebSphere\AppServer90\bin>WASPostUpgrade.bat C:\WAS70AdminAgentbackup -oldProfile 70AdminAgent01 -profileName 90AdminAgent01 
-traceString *=all=enabled -tracefile C:\WAS70AdminAgentbackup\logs\WASPostMigrationSummary.log -username myuser -password mypass
```
2. Review warnings or errors in the console output and WASPostUpgrade logs.
  After the WASPostUpgrade command is complete, check the console output for Failed with errors or Completed with warnings messages. Then, check the following log files for any warnings or errors:
  - migration_backup_dir/logs/WASPostMigrationSummary.log
  - WASPostUpgrade.target_profile_name.timestamp.log
  - WASPostUpgrade.target_profile_name.trace
  If there are errors, fix the errors and run the WASPostUpgrade command again. Check whether the warnings affect any other migration or runtime activities on Version 9.0.
  
  If the command completed successfully, it is not necessary to check the logs for errors or warnings.
Start the Version 9.0 administrative agent and ensure that both Version 7.0 or later and Version 9.0 administrative agents are running.
1. Change to the new Version 9.0 administrative agent profile bin directory.
2. Run the startServer adminagent command.
3. Check the SystemOut.log file for warnings or errors.
  
  Note: This topic references one or more of the application server log files. As a recommended alternative, you can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM® i systems. You can also use HPEL in conjunction with your native z/OS® logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.
Migrate managed base application servers.
Avoid trouble: For the migration to be successful:
- Managed base application servers must be located on the same machine as the associated administrative agent.
- The node names must be the same on the Version 9.0 and previous releases.
- Stop the AppSrv server before running a migration if you have a Windows platform and plan to migrate a SIB component.
For each managed base application server that you plan to migrate to Version 9.0, perform the following steps:
1. Create the target base application server profile. Run the manageprofiles command with the appropriate parameters to create a new managed profile.
  For example:
```
C:\WebSphere\AppServer90\bin>manageprofiles.bat -create -profileName 90AppSrv01 
-profilePath C:\WebSphere\AppServer90\profiles\AppSrv01
-templatePath C:\WebSphere\AppServer90\profileTemplates\default 
-serverType APPLICATION_SERVER -nodeName AppSrv01Node01 
-cellName AppSrv01Cell01 -hostName mynode1host.company.com
```
2. Run the WASPreUpgrade command to save the current managed base application server information to a migration backup directory. Choose a new directory for the backup files.
  For example:
```
C:\WebSphere\AppServer90\bin>WASPreUpgrade.bat C:\WAS70Appserver01backup 
C:\WebSphere\AppServer70 -oldProfile 70AppSrv01 -traceString *=all=enabled 
-summaryLogName C:\WAS70Appserver01backup\logs\WASPreMigrationSummary.log
```
3. Review warnings or errors in the console output and WASPreUpgrade logs.
  After the WASPreUpgrade command is complete, check the console output for Failed with errors or Completed with warnings messages. Then, check the following log files for any warnings or errors:
  - migration_backup_dir/logs/WASPreMigrationSummary.log
  - WASPreUpgrade.timestamp.log
  - WASPreUpgrade.trace
  If there are errors, fix the errors and run the WASPreUpgrade command again. Check whether the warnings affect any other migration or runtime activities on Version 9.0.
  
  If the command completed successfully, it is not necessary to check the logs for errors or warnings.
4. Run the WASPostUpgrade command to restore the saved managed application server profile configuration into the new Version 9.0 base application server profile.
  
  Avoid trouble: This command requires additional parameters and the following example assumes that security is enabled on both administrative agents.
  For example:
```
C:\IBM\WebSphere\AppServer90\bin>WASPostUpgrade.bat C:\WAS70Appserver01backup 
-oldProfile 70AppSrv01 -profileName 90AppSrv01 -traceString *=all=enabled 
-summaryLogName C:\WAS70Appserver01backup\logs\WASPostMigrationSummary.log 
-oldAdminAgentProfilePath C:\WebSphere\Appserver70\profiles\70AdminAgent01
-oldAdminAgentHostname myhostname -oldAdminAgentSoapPort 8879 
-oldAdminAgentUsername myusername -oldAdminAgentPassword mypassword 
-newAdminAgentProfilePath C:\WebSphere\AppServer90\profiles\90AdminAgent01 
-newAdminAgentHostname myhostname -newAdminAgentSoapPort 8887 
-newAdminAgentUsername myusername1 -newAdminAgentPassword mypassword1
```
5. Review warnings or errors in the console output and WASPostUpgrade logs.
  After the WASPostUpgrade command is complete, check the console output for Failed with errors or Completed with warnings messages. Then, check the following log files for any warnings or errors:
  - migration_backup_dir/logs/WASPostMigrationSummary.log
  - WASPostUpgrade.target_profile_name.timestamp.log
  - WASPostUpgrade.target_profile_name.trace
  If there are errors, fix the errors and run the WASPostUpgrade command again. Check whether the warnings affect any other migration or runtime activities on Version 9.0.
  
  If the command completed successfully, it is not necessary to check the logs for errors or warnings.
6. Start the migrated Version 9.0 managed application server.
7. Check the Version 9.0 managed application server SystemOut.log file for warnings or errors.
  
  Note: This topic references one or more of the application server log files. As a recommended alternative, you can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM i systems. You can also use HPEL in conjunction with your native z/OS logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.

Results

You migrated an administrative agent profile and its associated managed base application servers from WebSphere Application Server Version 7.0 or later to Version 9.0 using the migration tools. You can stop the Version 7.0 or later administrative agent, and you can assign the Version 7.0 or later ports to the Version 9.0 administrative agent.