7 Migrating Your Application
This topic includes the following sections:
7.1 What Is Migration?
Under normal circumstances, an administrator performs daily
administrative tasks on the configured MASTER
machine.
The DBBL on the MASTER
machine monitors other machines
in a configuration, handles configuration updates, and broadcasts
dynamic changes to the TMIB
. If the
MASTER
machine fails, for example, due to a machine
crash, database corruptions, Oracle Tuxedo system problems, network
partitioning, or application faults, the application does not stop
running. Clients can still join the application, servers can still
service requests, and naming is still available on each local
machine. However, until the MASTER
machine is
restored, servers cannot be activated or deactivated, and an
administrator cannot dynamically reconfigure the system.
Similarly, application servers are configured to run on specific
machines to service client requests. However, if a machine fails or
must be brought down to be serviced, the servers on that machine
become unavailable. In each case, you can migrate the servers to a
configured BACKUP
or alternate machine.
An administrator who performs a migration in preparation for shutting down a machine for service or upgrading, does not face the problems inherent in a machine failure. Therefore an administrator in this situation has a relatively high degree of control over migration activities.
- Performing a Master Migration
- Migrating a Server Group
- Migrating Machines
- Performing a Scheduled Migration
Parent topic: Migrating Your Application
7.1.1 Performing a Master Migration
A master migration is the process of moving the DBBL from the
configured MASTER
machine to the configured
BACKUP
machine so that servers can continue to be
serviced while the configured MASTER
machine is down.
To start a migration, an administrator requests that the configured
BACKUP
assume the role of acting MASTER
,
and the configured MASTER
, the role of acting
BACKUP
. The acting MASTER
then performs
all administrative functions: it begins monitoring other machines
in the configuration and accepts any dynamic reconfiguration
changes.
In the following figure, Machine 2, the configured BACKUP
machine, assumes the role of MASTER
, while Machine 1, the configured MASTER
, assumes the role of acting BACKUP
. When the configured MASTER
is available again, it can be reactivated from the acting MASTER
(that is, the configured BACKUP
). The configured MASTER
then regains control as acting MASTER
.
Figure 7-1 Performing a Master Migration

Parent topic: What Is Migration?
7.1.2 Migrating a Server Group
For each group of servers, an administrator specifies a primary machine and an alternate machine. The process of migrating a server group involves activating the server group on the alternate machine.
In the figure below, GroupA is assigned to Machine 1 (that is, Machine 1 is configured as the primary machine); Machine 2 is configured as the alternate machine for GroupA. After migration, GroupA is activated on Machine 2, which means that all servers in this group and the services associated with them, are available on Machine 2 (the acting primary).
Figure 7-2 Migrating a Server Group

Parent topic: What Is Migration?
7.1.3 Migrating Machines
While it is sometimes useful to migrate only a single server group, it is more often necessary to migrate an entire machine. This type of migration may be necessary, for example, when a computer fails. Migrating a machine involves migrating each of the server groups running on the machine. An alternate machine must be configured for each server group.
Parent topic: What Is Migration?
7.1.4 Performing a Scheduled Migration
In a controlled situation, such as when a computer needs to be offline for a while, or needs to be upgraded, an administrator can preserve information about the current configuration for servers and services, and use that information when activating servers on alternate machines. Such use of configuration information is possible because server entries are retained on a primary machine, even after the servers are deactivated and become unavailable in response to a request for a migration.
You can migrate an entire server group or an entire machine. Migration of an entire machine is possible when the same machine is configured as the alternate for all the server groups on a primary machine. When that is not the case (that is, when different alternate machines are configured for different server groups on a primary machine), then the servers must be migrated by group, rather than by machine.
In the following figure, Machine 1 is the configured MASTER
and the primary machine for GroupB; Machine 2 is the configured BACKUP
. Server GroupB is configured with Machine 1 as its primary machine and Machine 3 as its alternate. If Machine 1 is taken down, Machine 2 becomes the acting MASTER
, and Server GroupB is deactivated, migrated to its alternate (Machine 3), and reactivated.
Figure 7-3 Performing a Scheduled Migration

After deactivating all the servers in a group, you can migrate the group from the acting primary to the acting alternate. You do not need to specify which servers are running, which services are currently advertised, or which, if any, dynamic configuration changes are being made. The configured alternate machine obtains this information from the configuration information for the servers that is available on the configured primary machine, when the servers are deactivated. If data-dependant routing is being used and will continue to be used on the alternate machine, services are routed on the basis of the target group name, instead of the target machine name.
Whether you need to migrate an entire application or only portions of it, be sure to make the necessary changes with minimal service disruption. The integrity of all machines, networks, databases, and other components of your application must remain intact. The Oracle Tuxedo system provides a way to migrate an application while preserving the integrity of all its components.
Parent topic: What Is Migration?
7.2 Migration Options
The Oracle Tuxedo system allows you to migrate:
-
MASTER
machine to aBACKUP
machine, and vice-versa - A server group from its primary machine to its alternate machine
- All server groups on a primary machine to an alternate machine
- A transaction log
- A server group from its primary machine to its alternate machine
You can also cancel a migration.
By migrating a combination of the application components listed here, and using the system utilities for recovering a partitioned network, you can migrate entire machines.
Parent topic: Migrating Your Application
7.3 How to Switch the Master and Backup Machines
When a MASTER
machine must be shut down for
maintenance, or is no longer accessible due to an unanticipated
problem (such as a partitioned network), then you must transfer the
work of the MASTER
to a configured BACKUP
machine.
Note:
Before you can migrate theMASTER
, both the MASTER
and BACKUP
machines must be running the same release of the Oracle Tuxedo system software.
This type of switching is done by migrating the DBBL from the
MASTER
to the BACKUP
. To migrate the
DBBL, enter the following command:
tmadmin master
In most cases, you need to migrate application servers to alternate sites, or restore the MASTER
machine. For more detail about the tmadmin
command, see the reference tmadmin(1) page in the File Formats, Data Descriptions, MIBs, and System Processes Referenc.
7.3.1 Examples of Switching MASTER and BACKUP Machines
The following two sample tmadmin
sessions show how to switch
MASTER
and BACKUP
machines regardless of whether the
MASTER
machine is accessible from the BACKUP
machine. In
Listing7‑1, the MASTER
machine is accessible, so the DBBL
process is migrated from the MASTER
to the BACKUP
.
Listing 7‑1 Switching MASTER and BACKUP When MASTER Is Accessible from BACKUP
$ tmadmin
tmadmin - ................................;...................................
>master
are you sure? [y,n] y
Migrating active DBBL from SITE1 to SITE2, please wait...
DBBL has been migrated from SITE1 to SITE2
> q
In Listing 7‑2, because the MASTER
machine is not accessible from the machine, the DBBL
process is created on the BACKUP
machine on backup node (SITE2).
Listing 7‑2 Switching MASTER and BACKUP When MASTER Is Not Accessible from BACKUP
$ tmadmin
...
TMADMIN_CAT:199: WARN: Cannot become administrator.Limited set of commands available.
> master
Are you sure? [y, n] y
Creating new DBBL on SITE2, please wait ...
New DBBL created on SITE2
> q
$ tmadmin
....
>pcl SITE1
Cleaning the DBBL.
Pausing 10 seconds waiting for system to stabilize.
3 SITE1 servers removed from bulletin board
>q
In Listing 7‑3 and Listing 7‑4, after the old master (SITE1) becomes accessible again, execute the following commands to make the new MP mode work well. Make sure tlisten on both nodes starts up.
Listing 7‑3 Make Sure the New MP Mode Works Well After the Old Master Is Accessible Again on Site 1
$ tmadmin
...
>pcl SITE2
Cleaning the DBBL.
Pausing 10 seconds waiting for system to stabilize.
3 SITE2 servers removed from bulletin board
> q
$tmshutdown -y
Listing 7‑4 Make Sure the New MP Mode Works Well After the Old Master Is Accessible Again on Site 2
$ tmadmin
...
> boot -B SITE1 -l SITE1
INFO:....................., 64-bit, Patch Level (none)
Booting admin processes ...
exec BBL -A:
on SITE1 -> process id=15044 ... Started.
Booting server processes ...
exec serverping -A :
on SITE1 -> process id=15053 ... Started.
2 processes started.
>q
Parent topic: How to Switch the Master and Backup Machines
7.4 How to Migrate Server Groups
- Configure an alternate location in the
LMID
parameter (for the server group being migrated) in theGROUPS
section of theUBBCONFIG
file. Servers in the group must specifyRESTART=Y
and theMIGRATE
option must be specified in theRESOURCES
section of theUBBCONFIG
file. - If you are planning to migrate a group of servers, shut down each server in the group by issuing the following command:
tmshutdown -R -ggroupnam
- Start a
tmadmin
session by entering the following command:tmadmin
- To migrate all the servers in a single group, enter:
migrategroup(migg)
- To migrate all the server groups on a machine (as specified by an LMID), enter
migratemach(migm)
Note:
This command takes the name of a single server group as an argument.
- How to Migrate a Server Group When the Alternate Machine Is Accessible from the Primary Machine
- How to Migrate a Server Group When the Alternate Machine Is Not Accessible from the Primary Machine
- Examples of Migrating a Server Group
Parent topic: Migrating Your Application
7.4.1 How to Migrate a Server Group When the Alternate Machine Is Accessible from the Primary Machine
To migrate a server group when the alternate machine is accessible from the primary machine, complete the following procedure.
- From the
MASTER
machine, shutdown the group to be migrated by entering the following command:tmshutdown -R -g
groupname - On the primary machine, start a
tmadmin
session by entering the following command:tmadmin
- Migrate the appropriate group by entering the following command:
migrategroup groupname
- If necessary, migrate the transaction log.
- If necessary, migrate the application data
Parent topic: How to Migrate Server Groups
7.4.2 How to Migrate a Server Group When the Alternate Machine Is Not Accessible from the Primary Machine
To migrate a server group when the alternate machine is not accessible from the primary
machine, switch theMASTER
and BACKUP
machines, if necessary.
- On the alternate machine, start a
tmadmin
session by entering the following command:tmadmin
- Request cleanup and restart of any servers on the primary machine that require these operations by entering the following command:
pclean
primary_machine
- Transfer the appropriate server group to a configured alternate machine by entering the following command
migrate
groupname
- Boot the newly migrated server group by entering the following command:
boot -g
groupname
Parent topic: How to Migrate Server Groups
7.4.3 Examples of Migrating a Server Group
The following two sample sessions show how you can migrate a server group, regardless of whether the alternate machine is accessible from the primary machine. In Listing 7‑5, the alternate machine is accessible from the primary machine.
Listing 7‑5 Migrating a Group When the Alternate Machine Is Accessible from the Primary Machine
$ tmshutdown -R -g GROUP1
Shutting down server processes...
Server ID = 1 Group ID = GROUP1 machine = SITE1: shutdown succeeded
1 process stopped.
$ tmadmin
tmadmin - .................................
> migg GROUP1
migg successfully completed
> q
In Listing 7‑6, the alternate machine is not accessible from the primary machine.
Listing 7‑6 Migrating a Group When the Alternate Machine Is Not Accessible from the Primary Machine
$ tmadmin
tmadmin - ..............................; ............
> pclean SITE1
Cleaning the DBBL.
Pausing 10 seconds waiting for system to stabilize.
3 SITE1 servers removed from bulletin board
> migg GROUP1
migg successfully completed.
> boot -g GROUP2
Booting server processes ...
exec simpserv -A :
on SITE2 -> process id=22699 ... Started.
1 process started.
>q
Parent topic: How to Migrate Server Groups
7.5 How to Migrate Server Groups from One Machine to Another
- Use the
LMID
parameter to name the processor on which the server group(s) have been running. The alternate location must be the same for all server groups on theLMID
. - In the
RESOURCES
section of theUBBCONFIG
file, set the following parameters- Set
RESTART=Y
for each server on the machine indicated by theLMID
. - Specify the
MIGRATE
- Set
- Shut down all server groups and mark the servers in the groups as restartable by entering the following command:
tmshutdown -R
- Use the tmadmin(1)
migratemach
(migm
) command to migrate all server groups from one machine to another when the primary machine must be shut down for maintenance or when the primary machine is no longer accessible. (The command takes one logical machine identifier as an argument.)
- How to Migrate Machines When the Alternate Machine Is Accessible from the Primary Machine
- How to Migrate Machines When the Alternate Machine Is Not Accessible from the Primary Machine
- Examples of Migrating a Machine
Parent topic: Migrating Your Application
7.5.1 How to Migrate Machines When the Alternate Machine Is Accessible from the Primary Machine
To migrate a machine when the alternate machine is accessible from the primary machine, complete the following procedure.
- From the
MASTER
machine, shutdown the primary machine to be migrated by entering the following command:tmshutdown -R -1
primary_machine
- On the MASTER machine, start a tmadmin session by entering the following command:
tmadmin
- At the
tmadmin
prompt, migrate the appropriate machine by entering the following command:migratemach
primary_machine
- If necessary, migrate the transaction log.
- If necessary, migrate the application data.
Parent topic: How to Migrate Server Groups from One Machine to Another
7.5.2 How to Migrate Machines When the Alternate Machine Is Not Accessible from the Primary Machine
To migrate a machine when the alternate machine is not
accessible from the primary machine, switch the MASTER
and BACKUP
machines, if necessary.
- On the alternate machine, start a
tmadmin
session by entering the following command:tmadmin
- Request cleanup and restart of the primary machine that require
these operations by entering the following command:
pclean primary_machine
- Transfer the appropriate server group to a configured alternate
machine by entering the following command:
migratemach primary_machine
- Boot the newly migrated server group by entering the following
command:
boot -l
alternate_machine
Parent topic: How to Migrate Server Groups from One Machine to Another
7.5.3 Examples of Migrating a Machine
Listing 7‑7 shows how to migrate machines. In the first example, the alternate machine is accessible from the primary machine.
Listing 7‑7 Migrating a Machine When the Alternate Machine Is Accessible from the Primary Machine
$ tmshutdown -R -l SITE1
Shutting down server processes...
Server ID = 1 Group ID = GROUP1 machine = SITE1:shutdown
succeeded 1 process stopped.
$ tmadmin
tmadmin - .............................;............
> migm SITE1
migm successfully completed
>q
In Listing 7‑8, the alternate machine is not accessible from the primary machine.
Listing 7‑8 Migrating a Machine When the Alternate Machine Is Not Accessible from the Primary Machine
$ tmadmin
tmadmin - .............................;............
>pclean SITE1
Cleaning the DBBL.
Pausing 10 seconds waiting for system to stabilize.
3 SITE1 servers removed from bulletin board
> migm SITE1
migm successfully completed.
> boot -l SITE2
Booting server processes ...
exec simpserv -A :
on SITE2 -- process id=22782 ... Started.
1 process started.
>q
Parent topic: How to Migrate Server Groups from One Machine to Another
7.6 Automatic Migration
When only one logical machine fails (unreachable), the entities (DBBL and server groups) on that machine will be migrated by Automatic Migration feature if both such feature is enabled and the entity has backup machine defined in UBB. If the machine is unreachable merely due to network issue and the automatic migration is evoked, once the network issue is resolved and the “dead” machine comes back, one of the duplicate entities will be removed.
To enable the Automatic Migration feature, two threshold options
are required to be configured in *RESOURCES
section of
UBBCONFIG
-
DBBLFAILOVER
numeric_value
(0 <= num < 32768)/>DBBLFAILOVER*SANITYSCAN*SCANUNIT
is the time threshold for migratingDBBL
. This parameter is specified in seconds, or milliseconds ifSCANUNIT
is specified inmilliseconds
. The Automatic Migration for DBBL will be enabled only ifDBBLFAILOVER
is configured greater than 0. -
SGRPFAILOVER*SANITYSCAN*SCANUNIT
is the time threshold for migrating server groups. This parameter is specified in seconds, or milliseconds ifSCANUNIT
is specified inmilliseconds
. If not specified,SGRPFAILOVER
will be set as 0 by default. The Automatic Migration for server groups will be enabled only ifSGRPFAILOVER
is configured greater than 0/>SGRPFAILOVER*SANITYSCAN*SCANUNIT
is the time threshold for migrating server groups. This parameter is specified in seconds, or milliseconds ifSCANUNIT
is specified inmilliseconds
. If not specified, SGRPFAILOVER will be set as 0 by default. The Automatic Migration for server groups will be enabled only ifSGRPFAILOVER
is configured greater than 0./> Besides that, two related attributes TA_DBBLFAILOVER and TA_SGRPFAILOVER are defined in T_DOMAIN class for MIB operations.
For more information, see the UBBCONFIG(5) or TM_MIB(5).
Parent topic: Migrating Your Application
7.7 How to Cancel a Migration
If you decide, after deactivating a server group or machine, that you do not want to continue, you can cancel the migration before reactivating the server group or machine. All the information in the name server for the deactivated servers and services is deleted.
To cancel a migration after a shutdown but before issuing the migrate
command, enter one of the following commands shown in the table below.
Cancel | Command | Result |
---|---|---|
Server migration | tmadmin migratemach -cancel or tmadmin migg -cancel |
Server entries are deleted from the bulletin board. You must reboot the servers once the migration procedure is canceled. |
Machine migration | tmadmin migratemach -cancel or tmadmin migm -cance l
|
The migration is stopped. |
7.7.1 Example of a Migration Cancellation
The following sample tmadmin
session in Listing 7‑9 shows how a server group and a machine can be migrated between their respective primary and alternate machines.
Listing 7‑9 Canceling a Server Group Migration for GROUP1
$tmadmin
tmadmin - ......................; ..........
> psr -g GROUP1
a.out Name Queue Name Grp Name ID RqDone Ld Done CurrentService
---------- ---------- -------- -- ------ ------- ---------------
simpserv 00001.00001 GROUP1 1 - - (DEAD MIGRATING)
> psr -g GROUP1
TMADMIN_CAT:121: No such server
migg -cancel GROUP1
>boot -g GROUP1
Booting server processes...
exec simpserv -A:
on SITE1 ->process id_27636 ... Started. 1 process started.
> psr -g GROUP1
a.out Name Queue Name Grp Name ID RqDone Ld Done Current Service
---------- ---------- -------- -- ------ ------- ---------------
simpserv 00001.00001 GROUP1 1 - - ( - )
> q
Parent topic: How to Cancel a Migration
7.8 How to Migrate Transaction Logs to a Backup Machine
To migrate a transaction log to a BACKUP
machine,
complete the following procedure.
- Start a
tmadmin
session by entering the following command:tmadmin
- Shut down the servers in all the groups that write to the log, to prevent them from writing further entries.
- Dump the
TLOG
into a text file by running the following command:dumptlog [-z config] [-o offset] [-n filename] [-g groupname]
Note:
The TLOG is specified by the config and offset arguments. The value of offset defaults to 0; name defaults to TLOG. If the -g option is chosen, only those records coordinated by the TMS from groupname are dumped. - Copy
filename
to the BACKUP machine. - Read the file into the existing
TLOG
for the specified machine by entering the following command:loadtlog -m machine filename
- Force a warm start of the
TLOG
by entering the following command:logstart machine
TLOG
and uses it to create an entry in the transaction table in shared memory. - Migrate the servers to the
BACKUP
machine.
Parent topic: Migrating Your Application