5 Managing the Oracle Files Domain

Use the Oracle Enterprise Manager Web site to perform a variety of domain operations, including starting and stopping the Oracle Files domain, starting and stopping servers, and managing nodes. You can also manage the Oracle Files domain from the command line using ifsctl and opmnctl.

Topics in this chapter include:

About the Oracle Files Domain
Starting and Stopping the Oracle Files Domain
Migrating the Domain Controller
Managing the Node Processes
Starting, Stopping, Suspending, and Resuming Servers
Managing the Oracle Files Domain from the Command Line
Oracle Process Management and Notification

About the Oracle Files Domain

The domain controller manages the set of nodes comprising the domain. The domain controller controls which nodes are running, tracks the status of each node, and allows nodes to be monitored and administered. The Oracle Files software runs as a set of middle-tier processes, called nodes. Each node executes on a particular computer, or host. Although a domain's nodes are often split across a set of hosts, a single host can have more than one Oracle Files node. Each node has a name, which is unique across the Oracle Files domain. Oracle Files nodes are processes of Oracle Files managing one or more services and servers (agents and protocols).

There are two types of nodes: regular nodes, and HTTP nodes. The Oracle Files HTTP node runs as part of an Oracle9iAS Containers for J2EE (OC4J) process.

The domain controller polls the nodes that are configured to run under its control. Once all the nodes are identified, you will see them under the list of nodes for the specific domain.

In order to control the Oracle Files domain and the nodes using the Oracle Enterprise Manager Web site, the Oracle Enterprise Manager process must be running on each host that comprises the domain. See Table 4-1 for information about how to start and stop the Oracle Enterprise Manager process.

The fully-qualified name for an Oracle Files domain is:

ifs://db_host:port:db_service:files_schema

For example:

ifs://testcomputer.us.oracle.com:1521:filesservice:filesschema

Starting and Stopping the Oracle Files Domain

This section provides instructions for starting and stopping the Oracle Files domain using the Oracle Enterprise Manager Web site.

From the Oracle9iAS Farm Home page, click the name of the application server on which Oracle Files is running. The Oracle9iAS Instance Home page appears.

Figure 5-1 Oracle9iAS Instance Home Page

Description of the illustration oem01.gif

Among these components, Oracle Files domain targets appear in the following format:
```
iFS_db_host:port:db_service:files_schema
```
For example:
```
iFS_ifstst1.us.oracle.com:1521:ifstst1:hkfiles
```
After initial Oracle Files configuration, you must restart the Oracle Enterprise Manager process (see Table 4-1). If you access the Oracle Enterprise Manager Web site after configuration without restarting the Oracle Enterprise Manager process, the Oracle Files domain link will not be active.
From the Oracle9iAS Home page, click the name of the Oracle Files domain you want to manage.

The Oracle Files Home page appears, showing the status of the domain controller and the set of nodes that belong to the domain. A checkmark icon in the Status column means the component has been started.

Under certain conditions, such as after an upgrade, you will be prompted to enter the Oracle Files system user name and password when you navigate to the Oracle Files Home page in the Oracle Enterprise Manager Web site. If you see this prompt, you must provide the system user name and password in order to see elements of the Oracle Files domain from the Oracle Files Home page in the Oracle Enterprise Manager Web site.

You can avoid this behavior by manually encrypting the system password in targets.xml. See "Encrypting the System Password in targets.xml" for more information.

Figure 5-2 Oracle Files Home Page

Description of the illustration oem02.gif
Start, stop, or refresh the domain, as follows. Some operations are performed on local domain components, while others are performed on the entire domain.
- To start all the components on the local middle-tier host, click Start Local Components. To start a single local component, select it and click Start.
  
  You must restart the HTTP node's OC4J process whenever you restart the Oracle Files domain. See "Managing HTTP Nodes" for more information.
- To stop the entire domain, click Stop Domain. This action stops everything, including local and remote components. To stop a single local component, select it and click Stop.
- To refresh the domain with the latest changes, click Refresh Components. This action will update the domain with the latest node changes, including nodes added, nodes removed, and nodes marked active or inactive.
If the selection button for a particular component is greyed out, that component is not located on the local host. Connect to the Oracle Enterprise Manager Web site on the remote host to start or stop these components.

You can also migrate the domain controller from another host to the local host. See "Migrating the Domain Controller" in the following section for more information.

Migrating the Domain Controller

The domain controller is one of the most critical components of the Oracle Files domain. The domain controller establishes control over the nodes that make up the domain, starts and stops the domain, and performs a variety of other tasks. For this reason, it is important to ensure that the domain controller is running.

An administrator's ability to manage the domain decreases significantly when the domain controller goes down, even though some portions of the domain may still be usable. To avoid compromising the availability of the system, you can migrate the domain controller to another middle-tier host. This option allows you to re-enable the domain controller even when the middle-tier instance that hosted the domain controller fails.

Note:

You can only migrate the domain controller when it is not running.

Migrating the Domain Controller to a New Middle-Tier Host

New middle-tier hosts are set up through the Oracle Files Configuration Assistant. During the process of configuration, you can indicate whether the domain controller is to be run on the new middle-tier host.

The domain controller will be migrated to the new domain instance as part of the configuration process. See the Oracle Files chapter of the Oracle Collaboration Suite Installation and Configuration Guide for instructions on how to set up a new middle tier using the Oracle Files Configuration Assistant.

Migrating the Domain Controller to an Existing Middle-Tier Host

You can migrate the domain controller to an existing middle-tier instance using the Oracle Enterprise Manager Web site.

The following steps assume that the domain controller is currently on Host 1, and you wish to migrate it to Host 2.

Access the Oracle Enterprise Manager Web site for Host 2 (in other words, the host where you want the domain controller to be migrated).
Navigate to the Oracle Files Home page.

Figure 5-3 Oracle Files Home Page With Configure Domain Controller Button

Description of the illustration confdc.gif
Click Configure Domain Controller.
On the Confirmation page, click OK. The domain controller is migrated to the local host (Host 2).

Managing the Node Processes

There are two types of nodes: regular nodes and HTTP nodes. Although the domain can contain nodes on multiple middle-tier hosts, you can only start and stop nodes that are on your local host.

Managing Regular Nodes

The following sections explain how to start and stop regular nodes using the Oracle Enterprise Manager Web site.

Starting Regular Nodes

On the Oracle Files Home page, select the regular node that you want to start from the Components table.
Click Start.

The Node status column displays a checkmark icon, indicating that the node is up.

Stopping Regular Nodes

On the Oracle Files Home page, select the node to be stopped.
Click Stop.
On the Warning page, click Yes to stop the node.

The Node status column displays a down arrow icon, indicating that the node is down.

To permanently delete a node from the domain, you must either delete the node configuration object, or mark the node configuration inactive by deselecting the Active checkbox from the Edit Node Configuration page. See "Changing a Node Configuration" on page 4-3 for information about making a node configuration inactive. See "Deleting a Node Configuration" on page 4-7 for information about deleting node configuration objects.

Managing HTTP Nodes

HTTP nodes run in OC4J instances. The default OC4J instance name for Oracle Files is OC4J_iFS_files.

The following sections explain how to start and stop HTTP nodes using the Oracle Enterprise Manager Web site. You can also use opmnctl to start and stop HTTP nodes; see "Managing OC4J Processes" for more information.

Starting HTTP Nodes

Go to the Oracle9iAS Home page.
Select the OC4J instance for the HTTP node from the System Components table.
Click Start or Restart.

Note:
You must restart the OC4J instance whenever you restart the Oracle Files domain.

Stopping HTTP Nodes

To stop HTTP nodes using the Oracle Enterprise Manager Web site:

Go to the Oracle9iAS Home page.
Select the OC4J instance for the HTTP node from the System Components table.
Click Stop.
On the Warning page, click Yes to stop the OC4J instance.
Tip:
Use the following dcmctl command to check the status of the HTTP node:
dcmctl getState -co OC4J_iFS_files -v

The dcmctl command-line tool is located in $ORACLE_HOME/dcm/bin.

Permanently Deleting an HTTP Node

You cannot delete the OC4J instance for an HTTP node (OC4J_iFS_files), because these OC4J instances are created as protected instances. They cannot be deleted either through the Oracle Enterprise Manager Web site or through dcmctl; they can only be disabled.

Once the OC4J instance is disabled, Oracle Enterprise Manager or opmnctl will no longer attempt to start it.

To permanently remove an HTTP node, you must do the following:

Stop the OC4J instance for the HTTP node you want to remove.
Disable the OC4J instance:
1. From the Oracle9iAS Home page, click Enable/Disable Components.
2. On the Enable/Disable Components page, select the OC4J instance you want to disable and move it to the Disabled Components list.
3. Click OK.
Delete the node configuration object, or mark the node configuration inactive by deselecting the Active checkbox from the Edit Node Configuration page.

See "Deleting a Node Configuration" on page 4-7 for information about deleting node configuration objects. See "Changing a Node Configuration" on page 4-3 for information about making a node configuration inactive.

Starting, Stopping, Suspending, and Resuming Servers

A node configuration defines the behavior of a particular node. Which servers and agents start up with the node are determined by the node configuration selected. These servers and agents are started automatically when you start the domain, unless you specify otherwise. You can also manually start servers from the Node page.

Note:

Server is a generic term that applies to both protocol servers and agents.

On the Oracle Files Home page, click the name of the Oracle Files node you want to view. The Node page appears, showing the service and servers that comprise the node (see Figure 5-4).
Examine the Status column for the servers to see which servers are running or are stopped.

You can select a server and click one of the following buttons:

Start
Restart
Suspend
Resume
Stop
Unload

If you click a server name in order to directly edit the server properties, any changes you make remain active for this session only. To permanently change server properties, see "Changing a Server Configuration" on page 4-15. To change which servers start up automatically, see "Changing a Node Configuration" on page 4-3.

Figure 5-4 Services and Servers Sections of Node Page

Description of the illustration 3server.gif

Loading and Unloading Servers

In addition to starting and stopping servers, you can load and unload servers. Stopping/Starting (Restart) and Unloading/Loading are very different functions:

Restart stops and then starts the server. You can only restart servers that are started.
Unloading/Loading does the following:
- Stops the server, if it is not stopped already.
- Deletes the server.
- Creates a new instance of the server, picking up any changes to the server configuration properties.
- Returns the server to the state it was in when you clicked Reload (Stopped, Running, or Suspended).

You must Unload/Load the server for changes to configuration properties to take effect. Restarting the server will not pick up the changes. See "Reloading Servers" for more information.

Managing the Oracle Files Domain from the Command Line

As an alternative to using the Oracle Enterprise Manager Web site to start the domain and nodes, you can use the ifsctl command-line tool. The tool is located in:

$ORACLE_HOME/ifs/files/bin/

The general syntax is:

ifsctl command [switch ...] [argument ...]

For example:

ifsctl stop -v ifs://testcomputer.us.oracle.com:1521:filesservice:filesschema

Some commands require a schema password. In those instances, ifsctl prompts for the password, either on the terminal (UNIX) or using a dialog box (Windows).

The ifsctl commands are summarized in Table 5-1. For more details on the commands, type ifsctl.

Table 5-1 ifsctl Commands

Command	Use
ifsctl start [-v]^{Foot 1} [-n]^{Foot 2} [domain]^{Foot 3}	Launches any local Oracle Files nodes for the specified domain. ("Local nodes" are those configured to run on the computer where `ifsctl` is invoked.) If the domain controller for the specified domain runs locally, it is also launched. If domain is omitted, all local Oracle Files nodes and domain controllers for all domains for which the computer is registered are launched. The command also starts the domain controller if it has been launched (either locally or remotely) but is not yet started. If you include `-n`, the Oracle Files nodes and domain controllers are still launched, but the domain controller is not started (since starting an Oracle CM SDK domain requires a schema password).
ifsctl stop [-v] [domain]	Stops the specified domain. The domain controller and all nodes, whether local or remote, are stopped. If only one domain is registered for the computer, the domain may be omitted.
ifsctl stoplocalnodes [-v] [domain]	Stops the local nodes for the specified domain. Nodes running on other computers are not affected. The domain controller is not stopped. If only one domain is registered for the computer, the domain may be omitted.
ifsctl status [-v] [-n] [domain]	Displays the status of the specified domain. If the domain is omitted, displays the status for all domains for which the computer is registered.
ifsctl validateconfiguration [-v] [-p]^{Foot 4} [domain]	Synchronizes the Oracle Files registry file (on the local computer) with the domain registry (in the Oracle Files schema). This is normally done automatically; however, if the local computer's file system was restored from a backup (for example, after a disk failure), explicit synchronization might be required.

^{Footnote 1} All commands support a -v, "verbose" switch. This causes ifsctl to generate a log file with additional diagnostic information, located at $ORACLE_HOME/ifs/files/log/ifsctl.log.
^{Footnote 2} Including -n requests non-interactive operation; ifsctl does not prompt for the schema password.
^{Footnote 3} Specify [domain] in the format ifs://db_host:port:db_service:files_schema. You only need to specify [domain] when you have multiple Oracle Files domains on the same host.
^{Footnote 4} -p means "prune." If the registry file contains a domain that no longer exists (namely, if Oracle Files cannot connect to the database schema for that domain), the computer is deregistered from that domain.

Managing OC4J Processes

Oracle Files HTTP nodes run in OC4J processes. Because OC4J processes are not owned by Oracle Files (and might also be running non-Oracle Files servlets), ifsctl does not launch or stop OC4J processes. Use the Oracle Enterprise Manager Web site for this purpose, or you can run the following commands:

opmnctl startproc gid=OC4J_iFS_files
opmnctl restartproc gid=OC4J_iFS_files
opmnctl stopproc gid=OC4J_iFS_files
opmnctl status

You can run the OPMN command line from:

$ORACLE_HOME/opmn/bin/

See "Oracle Process Management and Notification" in the following section for more information.

Assuming the domain controller is running, when an OC4J process is launched, any Oracle Files HTTP nodes configured to run in that OC4J instance are automatically started. When an OC4J process is stopped, the HTTP nodes are stopped. Although ifsctl doesn't start and stop HTTP nodes, it does display their status.

Oracle Process Management and Notification

Oracle Process Management and Notification (OPMN) manages all the components within an application server instance, including Oracle HTTP Server, OC4J processes, and Oracle9iAS Web Cache. It channels all events from different components to all components interested in receiving them. OPMN consists of two components:

Oracle Process Manager (PM) is the centralized process management mechanism in Oracle9i Application Server and manages all Oracle9iAS component processes. It starts, stops, restarts, and detects the termination of these processes. When these processes are configured to start up, the characteristics of each set are specified in a configuration file:
```
$ORACLE_HOME/opmn/conf/opmn.xml
```
The PM starts and then waits for a command to start specific processes or all processes. At shutdown, the PM receives a request to stop one or more processes, or all processes and itself.
Oracle Notification System (ONS) is the transport mechanism for failure, recovery, startup, and other related notifications between components in Oracle9i Application Server.

Note:
OPMN cannot manage the Oracle Files domain controller process or the Oracle Files regular node processes.

To start Oracle HTTP Server, OC4J, and other processes, you can:

Use the Oracle Enterprise Manager Web site. On the Oracle9iAS Home page, select the relevant processes and click Start.

Or:

Use the OPMN command line in:
```
$ORACLE_HOME/opmn/bin/opmnctl
```

For more information on opmnctl syntax and usage, see the Oracle9i Application Server Administrator's Guide.