Skip Headers

Oracle9i Real Application Clusters Real Application Clusters Guard I - Concepts and Administration
Release 2 (9.2)
Part Number A96601-01
Go To Documentation Library
Home		 Go To Product List
Book List		 Go To Table Of Contents
Contents		 Go To Index
Index
Master Index
Feedback

Go to previous page Go to next page

4
Using Oracle Real Application Cluster Guard Commands

This chapter describes the Oracle Real Application Clusters Guard user commands. It contains the following sections:

Overview of the Oracle Real Application Clusters Guard Command-Line Utility

The PFSCTL control utility is responsible for starting, stopping, and operating Oracle Real Application Clusters Guard through its interaction with the cluster manager. It provides a command-line interface to the user. Many of the commands influence the behavior of the packs. A pack is software that ensures the availability of the set of resources required to run an Oracle instance. The pack controls the startup, shutdown, and restarting of Oracle Real Application Clusters Guard. There is one pack for each Oracle instance. Each pack controls the following resources on its node:

Oracle Real Application Clusters Guard User Commands

Table 4-1 shows the PFSCTL user commands that are available in Oracle Real Application Clusters Guard.

Table 4-1 Oracle Real Application Clusters Guard User Commands  
Command Description

pfsboot

Start all packs

pfshalt

Stop all packs

move_primary [seconds]

Move the primary role to the secondary instance in the specified number of seconds (optional). The default number of seconds is 30.

restore

Restore the pack to the secondary role

status

Display the state of the packs

stop_secondary [seconds]

Stop the secondary pack in the specified number of seconds (optional). The default number is seconds is 30.

bootone pack_name [-f]

Start the specified pack, with the option [-f] to start it on the foreign node.

Note: Pack name is case-sensitive.

haltone pack_name

Stop the specified pack.

Note: Pack name is case-sensitive.

switchover [seconds]

Move the primary role to the secondary instance, then restore the secondary role to the former primary instance. The default number of seconds is 30, which applies to moving the primary role.

call_home

Test user-defined call-home script

report [-f filename]
[-d yyyy/mo/dd-hh:mi:ss][-s]

Generates an uptime report.

-f filename: Specifies the filename for the report.
Example: report.rpt
Default: Standard output

-d yyyy/mo/dd-hh:mi:ss: Specifies the date and time from which to start the report (where yyyy is the year, mo is the month, dd is the date, hh is the hour based on 24 hours, mi is minutes, and ss is seconds
Example: 2001/08/10-12:10:10
Default: Generate the report from the beginning of the logs

-s: Generate only the uptime summary
Default: Generates the full report

help

List PFSCTL commands

quit/exit

Exit PFSCTL

To use PFSCTL commands, the ORACLE_SERVICE and DB_NAME environment variables must be defined.

Run PFSCTL commands as root because they invoke cluster-specific commands. PFSCTL commands are case-insensitive except for the pack name that is specified in the bootone and haltone commands. They may be run from any node.

Enter the commands by entering the name of the script and then the name of the command.

For example, to start all packs, enter the following command:

# pfsctl

You should see output similar to the following:

PFSCTL for hostA: Version 9.2.0.1.0 - Production on  Feb 25 2001 16:37:01
(c) Copyright 2001, 2002 Oracle Corporation. All rights reserved.
Welcome to PFSCTL. Type HELP for additional information.

ORACLE_SERVICE is set to SALES
DB_NAME is set to sales

When the PFSCTL prompt appears, enter the following command:

PFSCTL> pfsboot

You should see output similar to the following:

pfsboot command succeeded.

If there are multiple databases and you want to change to another Oracle Real Application Clusters Guard environment, then perform the following steps:

  1. Exit the current Oracle Real Application Clusters Guard environment: 
    PFSCTL> exit
  2. Set the ORACLE_SERVICE and DB_NAME environment variables to a new value. For example: 
    # export ORACLE_SERVICE=FIN
# export DB_NAME=fin
  3. Invoke PFSCTL: 
    # pfsctl

Starting Oracle Real Application Clusters Guard

Starting Oracle Real Application Clusters Guard means starting all the packs. Do this by entering the following commands:

# pfsctl
PFSCTL> pfsboot

You should see output similar to the following:

pfsboot command succeeded.

Displaying the Current Status of Oracle Real Application Clusters Guard

You can see the current status of the packs by entering the following commands:

# pfsctl 
PFSCTL> status

If both packs are up, then you should see output similar to the following:

hostA
Info: Pack PFS_SALES_hostA started.
hostB
Info: Pack PFS_SALES_hostB started.
Info: Local database instance is up.
Info: Remote database instance is up.
Info: Running primary role locally.
Info: Running secondary role on remote node.
Info: Cluster is up.
Info: Local node part of the cluster.
Info: Remote node part of the cluster.
Info: No internal process is running locally.
Info: No internal process is running remotely.
status command succeeded.

If Oracle Real Application Clusters Guard is running in nonresilient mode, then you should see output similar to the following:

hostB
Info: Pack PFS_SALES_hostA started.
hostB
Info: Pack PFS_SALES_hostB started.
Info: Local database instance is down.
Info: Remote database instance is up.
Info: No role running locally.
Info: Running primary role on remote node.
Info: Cluster is up.
Info: Local node part of the cluster.
Info: Remote node part of the cluster.
Info: No internal process is running locally.
Info: No internal process is running remotely.
status command succeeded.

If both packs are down, then you should see output similar to the following:

Info: Pack PFS_SALES_hostA stopped.
Info: Pack PFS_SALES_hostB stopped.
Info: Local database instance is down.
Info: Remote database instance is down.
Info: No role running locally.
Info: No role running on remote node.
Info: Cluster is up.
Info: Local node part of the cluster.
Info: Remote node part of the cluster.
Info: No internal process is running locally.
Info: No internal process is running remotely.
status command succeeded.

Restoring Oracle Real Application Clusters Guard After a Failure

When there is a failure on the primary node, Oracle Real Application Clusters Guard automatically fails over the pack that was operating on the failed node. To restore resilience, you must restore operation of the pack to the failed node, where it then has the secondary role.

To restore the pack to the secondary role, enter the following commands:

# pfsctl 
PFSCTL> restore

You should see output similar to the following:

restore command succeeded.

You can also use this command to restore resilience when the secondary pack fails.

Moving the Primary Role

Use the move_primary command if you want to do maintenance on the primary node. The move_primary command shuts down the instance on the primary node, using the SHUTDOWN TRANSACTIONAL statement. It triggers a failover after the instance is down, and the secondary node becomes the primary node. The optional seconds parameter specifies the time interval for the SHUTDOWN TRANSACTIONAL statement to complete. By default, the value is 30 seconds. If the SHUTDOWN TRANSACTIONAL statement times out, then PFSCTL issues a SHUTDOWN ABORT statement.

To do a clean shutdown, make sure that all active sessions are closed before you issue the move_primary command.

To move the primary role, enter commands similar to the following:

# pfsctl
PFSCTL> move_primary 40

You should see output similar to the following:

move_primary_40 command succeeded.

Switching Roles in Oracle Real Application Clusters Guard

After a failover, when you have restored resilience with the restore command, the primary role and the secondary role are not on their original nodes. If you want the roles to reside on their original nodes, then use the switchover command. The switchover command is equivalent to entering the move_primary command and then the restore command.

If you specify a number of seconds in the switchover command, then the number of seconds is applied to the SHUTDOWN TRANSACTIONAL statement that is part of moving the primary role. For example:

PFSCTL> switchover 40

If you do not specify a number of seconds, then the default value of 30 seconds is used.

The following example shows what happens when you use the switchover command. Invoke PFSCTL:

# pfsctl

The output shows that ORACLE_SERVICE is set to SALES:

PFSCTL for hostA: Version 9.2.0.1.0 - Production on  Feb 07 200118:15:10
(c) Copyright 2001 , 2002 Oracle Corporation.  All rights reserved.
Welcome to PFSCTL. Type HELP for additional information.

ORACLE_SERVICE is set to sales
DB_NAME is set to sales

Enter the status command to see where the primary and secondary roles are:

PFSCTL> status

You should see output similar to the following:

hostA
Info: Pack PFS_sales_hostA started.
hostB
Info: Pack PFS_sales_hostB started.
Info: Local database instance is up.
Info: Remote database instance is up.
Info: Running primary role locally.
Info: Running secondary role on remote node.
Info: Cluster is up.
Info: Local node part of the cluster.
Info: Remote node part of the cluster.
Info: No internal process is running locally.
Info: No internal process is running remotely.
status command succeeded.

It shows that the local host, hostA, has the primary role and hostB has the secondary role.

Enter the switchover command:

PFSCTL> switchover

You should see output similar to the following:

switchover command succeeded.

Enter the status command:

PFSCTL> status

You should see output similar to the following:

hostA
Info: Pack PFS_sales_hostA started.
hostB
Info: Pack PFS_sales_hostB started.
Info: Local database instance is up.
Info: Remote database instance is up.
Info: Running secondary role locally.
Info: Running primary role on remote node.
Info: Cluster is up.
Info: Local node part of the cluster.
Info: Remote node part of the cluster.
Info: No internal process is running locally.
Info: No internal process is running remotely.
status command succeeded.

It shows that hostA has the secondary role and hostB has the primary role. The switchover was successful.

See Also:

"Moving the Primary Role"

Halting Oracle Real Application Clusters Guard

When you need to perform a task which requires stopping Oracle Real Application Clusters Guard, use the pfshalt command. Such tasks include upgrading Oracle Real Application Clusters Guard and other Oracle software.

Stopping Oracle Real Application Clusters Guard means stopping all the packs. Do this by entering the following commands:

# pfsctl 
PFSCTL> pfshalt

You should see output similar to the following:

pfshalt command succeeded.

Halting a Single Pack

Use the haltone command when you want to stop a specific pack no matter whether it is primary or secondary or on which node it is running. You may want to stop a specific pack when you want to do maintenance work. The consequences of halting a pack are different depending on what state the system is in and which pack you want to stop. Table 4-2 shows different conditions and the consequences of using the haltone command.

Table 4-2 Consequences of Using the haltone Command
Initial Condition Consequence

The system is resilient. The pack you want to stop has the primary role.

The secondary pack becomes primary.

The system is resilient. The pack you want to stop has the secondary role.

The primary pack remains primary.

The system is not resilient.

No pack is running.

Stop a single pack by entering commands similar to the following:

# pfsctl 
PFSCTL> haltone PFS_SALES_hostA

PFS_SALES_hostA is the name of the pack that you want to stop.

You should see output similar to the following:

haltone_PFS_SALES_hostA command succeeded.

Starting a Single Pack

Use the bootone command to start a specific pack on either its home node or on its foreign node (using the -f option).

Start a pack on its foreign node if you want to bring up the relocatable IP address on that node. Enter a command similar to the following:

PFSCTL> bootone PFS_SALES_hostA -f

You should see output similar to the following:

bootone_PFS_SALES_hostA_-f command succeeded.

Now the PFS_SALES_hostA pack is running on its foreign node and its IP address is available on that node.

The bootone command is especially useful when you want to start the primary pack on the node that is not specified as the preferred primary node. The pfsboot command always starts the packs so that the primary instance runs on the preferred primary node. However, in some cases, you may want to start Oracle Real Application Clusters Guard with the primary role on the node that is not specified as the preferred primary node. There are several ways to do this, but using the bootone command is more efficient.

If the preferred primary node is Node A and you want to start the primary role on Node B, then perform the following steps:

  1. Stop the packs on both nodes: 
    PFSCTL> pfshalt

    You should see output similar to the following:

    pfshalt command succeeded.
  2. Start the pack whose home node you want to be the primary node. If the pack name is PFS_SALES_hostB, then enter the following command: 
    PFSCTL> bootone PFS_SALES_hostB

    You should see output similar to the following:

    bootone_PFS_SALES_hostB command succeeded.
  3. Start the other pack. If the pack name is PFS_SALES_hostA, then enter the following command: 
    PFSCTL> bootone PFS_SALES_hostA

    You should see output similar to the following:

    bootone_PFS_SALES_hostA command succeeded.

    Both packs are now running their home nodes. The instance on Node B has the primary role because it was started first.

    See Also:

    "Home and Foreign Nodes"

Stopping the Secondary Role

Use the stop_secondary command if you want to do maintenance on the secondary node. It shuts down the secondary instance. The optional seconds parameter specifies the time for the SHUTDOWN TRANSACTIONAL statement to complete. By default, the value is 30 seconds. Enter commands similar to the following:

# pfsctl
PFSCTL> stop_secondary 40

You should see output similar to the following:

stop_secondary_40 command succeeded.

Using Oracle Real Application Clusters Guard Commands for Planned Outages

You can use PFSCTL commands to shut down the instance on the node that you need to perform maintenance on. This section contains general instructions for planned outages on the node with primary role and the node with secondary role.

Note:

Recall that when one node is unavailable, Oracle Real Application Clusters Guard cannot perform failover. Plan accordingly.

Planned Outage on the Secondary Node

To use PFSCTL commands for a planned outage on the secondary node, perform the following steps on the primary node:

  1. Stop the secondary instance. Use commands similar to the following: 
    # pfsctl 
PFSCTL> stop_secondary

    You should see output similar to the following:

    stop_secondary command succeeded.
  2. Complete the desired maintenance on the secondary node.
  3. Restore the secondary instance to the secondary node. Use the following command: 
    PFSCTL> restore

    You should see output similar to the following:

    restore command succeeded.

Planned Outage on the Primary Node

To use PFSCTL commands for a planned outage on the primary node, perform the following steps on the secondary node:

  1. Move the primary role to the secondary instance. Use commands similar to the following: 
    # pfsctl 
PFSCTL> move_primary

    You should see output similar to the following:

    move_primary command succeeded.
  2. Complete the desired maintenance on the former primary node.
  3. Restore the secondary role to the former primary node. Use the following command: 
    PFSCTL> restore

    You should see output similar to the following:

    restore command succeeded.
  4. (Optional) Move the primary role back to the original primary node and restore the secondary role to the original secondary node. Use the following command: 
    PFSCTL> switchover

    You should see output similar to the following:

    switchover command succeeded.

Testing the Call-Home Script

When Oracle Real Application Clusters Guard detects a failure, the call-home feature executes a callout to a call-home script that has been customized by the user. The call-home script can be used to page or send e-mail, for example. The call-home script is located in:

$PFS_HOME/user/pfs_$ORACLE_SERVICE_callhome.sh

The call_home command provides a way to test the script.

To test your call-home script, enter the following commands:

# pfsctl
PFSCTL> call_home

Successful completion of the command results in the customized outcome, such as a page.

See Also:

"Setting Up the Call-Home Feature"

Listing the Oracle Real Application Clusters Guard Commands

To list the PFSCTL commands and their formats, enter the following commands:

# pfsctl
PFSCTL> help

You should see output similar to the following:

The following commands are available:


PFSBOOT
PFSHALT
MOVE_PRIMARY [seconds]
STOP_SECONDARY [seconds]
RESTORE
STATUS
SWITCHOVER [seconds]
REPORT [-f filename][-d yyyy/mm/dd-hh:mm:ss][-s]
QUIT
EXIT
BOOTONE [pack name] [-f]
HALTONE [pack name]
CALL_HOME
HELP
help command succeeded.

Generating the Uptime Report

Use the report command to generate an uptime report. For example, enter the following command:

PFSCTL> report -f report.txt -d 2001/11/09-16:42:00

You should see output similar to the following:

======================================================================
| Oracle Real Application Clusters Guard for Solaris: Version 9.2.0.1.0
|
| (c) Copyright 2001, 2002 Oracle Corporation.  All right reserved.
|
| Up Time Report generated by PFSCTL report on 11/09/01
======================================================================
Oracle service: SALES
Report time interval: 2001/11/09-16:42:00 -- 2001/11/09-17:00:31

Itemized downtime information:

Downtime Start          Node    Downtime End
Node    Interval (secs)
==========================================================================
Planned downtime
2001/11/09-16:55:42     hostA  2001/11/09-17:00:31     hostA  289

Unplanned downtime
 ----/--/-----:--:--               n/a     2001/11/09-16:42:00     hostA  0
2001/11/09-16:44:35     hostA  2001/11/09-16:44:45     hostB  10
2001/11/09-16:54:17     hostB  2001/11/09-16:54:32     hostA  15

Downtime summary:
Total planned downtime: 289 seconds
Total unplanned downtime: 25 seconds
Total downtime: 314 seconds
Availability for this interval: 97.7497%

Exiting PFSCTL

Use the exit or quit command to exit PFSCTL.

PFSCTL> exit
Go to previous page Go to next page
Oracle
Copyright © 2001, 2002 Oracle Corporation.
All Rights Reserved.
Go To Documentation Library
Home		 Go To Product List
Book List		 Go To Table Of Contents
Contents		 Go To Index
Index
Master Index
Feedback