2
Administering an Oracle 9iFS Domain

Administration of a runtime instance of Oracle 9iFS requires starting the domain and nodes and monitoring the performance of the domain. This chapter describes the components of the domain and use of the Oracle Enterprise Manager for Oracle9i Application Server. Topics include:

• The Oracle 9iFS Domain

• Starting Oracle 9iFS

• Monitoring the Performance of an Oracle 9iFS Domain

The Oracle 9iFS Domain

The basic administrative unit of Oracle 9iFS is the domain. A domain is a single Oracle 9iFS instance. Oracle 9iFS domains consist of several elements, running either on a single computer or spread across a set of interconnected computers (see Figure 2-1, "An Internet File System Domain").

Figure 2-1 An Internet File System Domain

Text description of the illustration 2domain.gif

The principal elements of an Oracle 9iFS domain are:

• A single domain controller. The domain controller manages the set of nodes comprising the domain. For example, the domain controller controls which nodes are running, tracks nodes' statuses, and allows nodes to be monitored and administered.

• One or more nodes. The Oracle 9iFS software runs on the database machine and 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 9iFS node. Each node has a name, which is unique across the Oracle 9iFS domain. Oracle 9iFS nodes are processes of Oracle 9iFS managing one or more services and servers (agents and protocols).

  Because the HTTP Server runs as part of a Jserv or OC4J process and is controlled outside of Oracle 9iFS, the HTTP Server runs in its own node. Typically, each Oracle 9iFS node will have an associated HTTP node.

• The Oracle 9iFS repository. All data managed by Oracle 9iFS resides in an Oracle 9i database schema, called the Oracle 9i repository. You specify the database instance and schema name of the repository during installation of Oracle 9iFS.

The domain controller, nodes, and repository comprise the logical elements of an Oracle 9iFS domain. However, a domain's physical configuration may be quite different than its logical configuration. There is no requirement that any element of the domain be on the same host as any other, or that any of element be on a different host than another. For small installations, the repository, nodes, and domain controller may all reside on a single host (Figure 2-1, "An Internet File System Domain"). Larger installations may use separate hosts for each element (Figure 2-2, "A More Complex Domain").

Figure 2-2 A More Complex Domain

Text description of the illustration 2dnodes.gif

You can use the Oracle9iAS Home Page to manage the domain (see Figure 2-3, "The Oracle9iAS Home Page".)

You can also use the Oracle Enterprise Manager Java Console to manage one or multiple domains.

Determining the logical and physical configurations of the Oracle 9iFS domain based on proposed use and expected load is a pre-installation step. You can change the domain's logical and physical configurations over time in response to changing requirements.

Figure 2-3 The Oracle9iAS Home Page

Text description of the illustration domaina4.gif

Oracle9i Application Server and OC4J

Oracle9iAS Containers for J2EE (OC4J) are fast, lightweight, and scalable J2EE containers that are written in Java and execute on a standard Java Virtual Machine (JVM). J2EE applications are modularized for reuse of application components, such as the user interfaces, which can be composed of Java Server Pages (JSP pages), dynamic HTML, and so on, as well as the business logic, which is usually contained in an Enterprise JavaBean (EJB). The J2EE containers also perform services for the application components, such as providing access to the APIs and lifecycle management.

Locators

Domain controllers and nodes are identified by locators. A locator is a Uniform Resource Locator (URL) that specifies the host on which the domain controller or node is running and its port number. The locator name appears as the node name.

For example, the locator of the domain controller in Figure 2-4, "iFS Top-level Page" is:

ifs_socket://samman-sun:53140

Figure 2-4 iFS Top-level Page

Text description of the illustration 1ifstop.gif

Guarded and Unguarded Nodes

Each node has a node guardian that monitors the node, detects error conditions, and attempts to recover from them. The node guardian runs in a separate process. Guarded nodes offer better fault recovery because the guardian can terminate and restart the node's process if necessary. Nodes are guarded by default. The node guardian is turned on and off in the node's configuration file. See Appendix D, "Process Configuration Files" for more information.

If a guarded node process fails, it is automatically re-launched by its node guardian, and is then automatically restarted by the domain controller. If an unguarded node fails, the failure is detected by the domain controller and the node remains unavailable until it is re-launched. The same is true if the node guardian process fails.

Individual nodes can by dynamically brought online and off-line by the administrator.

• To bring a new node online, the administrator adds the desired node to the list held by the domain controller and refreshes the already running domain controller, causing the node list to be re-read and the new node started without affecting the other running nodes.

• An administrator may temporarily take a node off-line by stopping it, causing the node process to terminate.

• To permanently take a node off-line, an administrator removes it from the domain controller's node list and refreshes the already running domain controller, causing the list to be re-read and the node to be stopped without affecting the other running nodes.

The Oracle 9iFS DAV Servlet and Oracle HTTP Server

The Oracle HTTP Server provides a number of components, including an Apache web server instance that works with OC4J. After installation, when you run ifssetup, you configure the Oracle 9iFS DAV servlet to work with the Oracle HTTP Server. (In fact, the WebDAV server is the same server as HTTP, since WebDAV uses HTTP as its underlying protocol. )

To use the web server, you need to start the web server after startup of your domain and launching of the HTTP node.

1. Go to $ORACLE_HOME/dcm/bin.

2. Run the script dcmctl start.

The special HTTP node gets started and you can access the Oracle 9iFS file system through the URL: <servername>:7777/ifs/files.

Oracle 9iFS provides HTTP and WebDAV support using a Java servlet running in the Oracle HTTP Server. By default, this servlet is loaded when the OC4J process is started. Once loaded, the servlet creates a node (the "HTTP node") in the Java VM of the servlet. The HTTP node has an Oracle 9iFS service which manages user sessions and provides access to the domain's repository, and an Oracle 9iFS server which provides HTTP and WebDAV protocol support.

Because its process is owned by the Oracle HTTP Server, an HTTP node is always unguarded.

Services and Servers

Each Oracle 9iFS node can have one or more services and one or more servers (see Figure 2-5). These services and servers are started automatically when you start the domain, unless you specify otherwise.

Figure 2-5 Services and Servers on an Oracle 9iFS Node

Text description of the illustration 2srvc_sr.gif

• Services. Each node supports a service with specific configuration parameters, such as language, default character set, credential managers, and many other characteristics, including connections to the database and other features affecting performance. Typically, a single service runs on each node. However, it is possible to run more than one service on a node to provide, for example, services with different configurations (for example, cache sizing or default language). However, every service on the node (and more generally, every service in the domain) must bind to the same repository. A service manages user sessions and allows those sessions to access the repository's data. Services have names which are unique across the node (but not necessarily unique across the domain).

• ServiceConfiguration. A ServiceConfiguration is a template for creating a service on a generic node. Each service configuration specifies values for properties such as the database instance and schema name of the repository, the sizes of the cache and database connection pools, the maximum number of sessions, and the service's default language and character set. Service configurations are uniquely named across the domain.

• Servers. A server is an application running on a node. Servers run inside the node's process, and against the node's services. Most servers are either protocol servers or agents. Like services, servers have names that are unique across the node (but not necessarily unique across the domain).
  • A protocol server opens a TCP/IP server socket, awaits connections from clients, and performs operations dictated by a protocol specification in response to client requests. The Oracle 9iFS FTP server is an example of a protocol server.

  • An agent runs unattended, performing predefined operations either periodically or in response to repository operations performed asynchronously by other servers. The Oracle 9iFS Garbage Collection Agent is an example of an agent.

    Once a server is running, it publishes a subset of the parameters and any other runtime information specific to the server. These are called dynamic properties. Some dynamic properties are published as soon as the servers are loaded, but not running. A subset of the properties may be changed, but only for that server, within that node, within that domain. Agents are writeable only when stopped.

• ServerConfiguration. A ServerConfiguration is a template for creating a particular type of server on a generic node. Server configurations specify their server types as Java classnames. In addition to the server type, each server configuration specifies values for parameters relevant to that type. For example, a server configuration for the Oracle 9iFS FTP server specifies the FTP port number, whether anonymous FTP connections are allowed, and the connection time-out period.

Since service and server parameters are stored in Oracle 9iFS along with your files and data as objects, you can use the Oracle 9iFS Node page to manage these parameters (see Figure 2-6, "Managing Services and Servers on the Node Page").

Figure 2-6 Managing Services and Servers on the Node Page

Text description of the illustration domaina5.gif

To change the dynamic properties of a server, first select the server on the Node page by clicking its name (see Figure 2-7, "Changing FTP Server Properties") to display its properties.

Figure 2-7 Changing FTP Server Properties

Text description of the illustration domaina3.gif

Only those properties that appear as links may be changed. For example, clicking the property:

IFS.PROTOCOLSERVERS.SESSION.DEFAULT.Delimiter

displays a page on which you can change the default value.

Figure 2-8 Changing the Value of a Dynamic Server Property

Text description of the illustration 2ftps2.gif

For more information on service and server configuration, see Chapter 5, "Service and Server Configuration".

Starting Oracle 9iFS

There are a number of different ways you can start Oracle 9iFS. Which way you choose depends on how you want to monitor or manage the Oracle 9iFS domain.

• Through the Enterprise Manager Console for Oracle9i Application Server, to monitor Oracle 9iFS as well as the Oracle9i Application Server and any applications running on the application server.

• Through the Oracle Enterprise Manager Java Console to have access to all Oracle 9iFS repositories on the network. See Appendix H, "Domain Administration with the Java-based Oracle Enterprise Manager Console" for more information.

• From the command line using scripts.

Starting Oracle 9iFS through the Enterprise Manager Console for Oracle9i Application Server

The Enterprise Manager Console for Oracle9i Application Server (Oracle9iAS) provides access to basic Oracle 9iFS domain and node functions, such as starting and stopping the domain, nodes, services, and servers. It also allows administrators to monitor and dynamically tune the domain's nodes, services, and servers.

Figure 2-9 Oracle 9iFS is a Component Displayed on the Oracle9iAS Home Page

Text description of the illustration domain16.gif

Start the Oracle 9iFS Domain Controller

1. Before you start the Oracle 9iFS domain, you must run the emctl start script to start the Enterprise Manager Console for Oracle9iAS. At the command line, enter:

   $oracle_home/bin/emctl start
   
   

2. From your web browser access the Oracle9iAS Home page by entering:

   http://hostname:1810/emd/console/targets
   
   

   The Oracle9iAS Home page lists all of the Oracle9iAS components or targets configured on the local host. Among these components, you'll find the Oracle 9iFS Domain targets and the Oracle 9iFS Node targets with type Internet File System Node.

3. From the Oracle9iAS Home page, click the Internet File System link. On Figure 2-9, this is the samman-sun:53140 link, not the Internet File System Node link. The Oracle 9iFS Top-level page displays, showing the status of the domain controller. It should be "Down."

4. Click the Launch Domain Controller button.

5. On the Host Credential page, enter the operating system user name and password and click OK.

   The status changes to "Launched."

6. Click the Start Domain button.

   The status changes to "Started."

Start the Nodes

Nodes usually come in sets: an instance of Oracle 9iFS and its corresponding HTTP node. You can only launch nodes on your local machine; the domain, however, can contain nodes on multiple middle-tier machines.

To launch the node on a local host (see Figure 2-10):

Figure 2-10 Select the Oracle 9iFS Node to Launch

Text description of the illustration 2nodest.gif

1. On the Oracle 9iFS Top-level page, Select the Internet File System node that you want to launch. Its status should be "Down."

2. Click Launch.

3. On the Host Credential page, enter the operating system user name and password and click OK. If successful, the Node status changes to "Up."

Stop a Domain

When you stop an Oracle 9iFS domain, you have a choice of stopping both the domain and the nodes or just the domain controller.

1. On the Oracle 9iFS Top-level page, click the Stop Domain button.

2. On the Warning page, specify whether or not to stop the nodes as well as the domain.

3. Click the Yes button.

   The domain status now says "Down." If you shut down the nodes, they no longer appear in the Nodes table because the domain controller is down.

Refresh A Domain

Refreshing a domain causes the domain controller to synchronize to the latest configuration of the nodes in the domain. This is useful if you add or remove nodes in the domain using Oracle 9iFS Configuration Assistant or Oracle 9iFS Manager or have launched additional nodes.

1. On the Oracle 9iFS Top-level page, click the Refresh Domain button.

   The domain status now says "Started." Any nodes you launched prior to refreshing are now started.

Stop a Node

You can stop a node from the Oracle 9iFS Top-level page. To permanently delete the node from the domain, however, you need to use Oracle 9iFS Manager to delete the Node Configuration object for that Oracle 9iFS node.

1. On the Oracle 9iFS Top-level page, select the node to be stopped.

2. Click Stop.

3. On the Warning page, click Yes to stop the node.

   The node is removed from the Nodes page. If you click the Refresh Domain button, the node is added to the Nodes page, and its status changes to "Down."

Starting Oracle 9iFS from the Command Line

To start Oracle 9iFS from the command line, use these scripts:

1. ifslaunchdc to bring up the domain controller process.

2. ifslaunchnode to bring up the node process

3. ifsstartdomain to activate the domain controller and nodes. This script requires the following parameters as input:
   • Domain controller locator, which includes hostname and port

   • Schema password

These scripts have been provided to start and stop the entire domain from the command line, without having to launch the Oracle Enterprise Manager Java Console.

The ifsstopdomain script, used to stop the domain, requires the same three parameters as the ifsstartdomain script .

Monitoring the Performance of an Oracle 9iFS Domain

To get an overall picture of the domain's performance or to continuously monitor the domain, use the Enterprise Manager Console for Oracle9i Application Server.

On the Oracle 9iFS Node page, click the Node Performance & Statistics link.

Figure 2-11 Node Properties

Text description of the illustration 2nodperf.gif

If you are running multiple nodes, you may prefer to use the monitoring tools built into the Oracle Enterprise Manager Console (see Appendix H, "Domain Administration with the Java-based Oracle Enterprise Manager Console").

To get a snapshot of domain performance or to monitor the domain, a set of pages graphically depicts domain performance. The display is dynamic; that is, the data is updated as time passes, so you should refresh the pages often.

1. On the page associated with the Oracle 9iFS domain, click the Domain Performance & Statistics link to navigate to the monitoring pages.

2. Select one of the four subtabs:
   • The General subtab for general information and information about document storage.

   • The Documents subtab for several pages of systemwide information about documents.

   • The Sessions subtab for a viewing the connected sessions by server type.

   • The Overall Usage subtab for monitoring sessions, threads, and memory by node and host.

3. To refresh the information, click the Refresh button.

4. When you are finished monitoring performance, use the "breadcrumbs" path display to navigate to another page.

The General Subtab

The General subtab monitors the Oracle 9iFS repository and its documents and users (see Figure 2-12). It provides general information and information about document storage, including:

• The database URL where statistics are calculated.

• The repository schema name.

• The number of users with accounts.

• The number of documents the users own.

• The maximum space, or quota, allotted to all users.

• The amount and percentage of the quota that users have consumed.

Figure 2-12 Monitor Document Storage on the General Subtab

Text description of the illustration domaina2.gif

The Documents Subtab

The Documents subtab gives you access to three displays:

• The Document Table listing document distribution by MIME type.

• The Document Distribution Chart showing consumed space by MIME type.

• The Document Consumption Chart showing the space consumed by document type.

To navigate between pages, make a selection from the Select a View drop-down list and click the Go button.

Document Table

This table (Figure 2-13) combines the information in both chart views and allows you to compare the number and consumed space of the various document types in Oracle 9iFS. MIME type is used because it is more descriptive than three-character extensions.

Figure 2-13 The Document Table Shows Information by MIME Type

Text description of the illustration 2doctabl.gif

Document Distribution Chart

The Document Distribution Chart (Figure 2-14) presents a graphical view of the number of each document type in Oracle 9iFS.

Figure 2-14 The Document Distribution Chart Depicts Documents by MIME Type'

Text description of the illustration 2dischrt.gif

Document Consumption Chart

The Document Consumption Chart (Figure 2-15) shows the space consumed by document type.

Figure 2-15 The Document Consumption Chart Shows Space Consumed by Type of Document

Text description of the illustration 2consump.gif

The Sessions Subtab

The Sessions subtab displays the Session Table, listing the connected sessions by server type and the number of sessions running on each, and the Session Chart, depicting online sessions by server type. To navigate between pages, make a selection from the Select a View drop-down list and click the Go button.

Session Table

The Session Table (Figure 2-16) shows the total number of connected sessions associated with each server.

Figure 2-16 See Total Sessions by Server on the Session Table

Text description of the illustration 2sesstab.gif

Session Chart

The Session Chart is a pie chart comparing the total number of connected sessions for each server type.

Figure 2-17 Compare Connected Sessions by Server Type on the Session Chart

Text description of the illustration 2sesscht.gif

The Overall Usage Subtab

The Overall Usage subtab displays Session charts by node and by host depicting the number of sessions and threads, Memory charts by node and by host showing current memory use in kilobytes, and a combined table view by node and by host summarizing the number of sessions and threads in use by each node. To navigate between pages, make a selection from the Select a View drop-down list and click the Go button.

If you have developed a custom application, and your Thread Count continues to increase over time and never decreases, then you may have a thread leak in your software. In particular, check that you are calling LibrarySession.disconnect() whenever a user disconnects or is timed out.

Overall Usage Table by Node

For each node, the Overall Usage Table by Node (Figure 2-18) presents the total number of connected sessions, the total number of threads, and the total memory consumed by each node.

Figure 2-18 Overall Usage by Node

Text description of the illustration 2usenode.gif

Overall Usage Table by Host

For each host, the Overall Usage Table by Host (Figure 2-19) presents the total number of connected sessions, the total number of threads, and the total memory consumed by each host.

Figure 2-19 Overall Usage by Host

Text description of the illustration 2usehost.gif

Overall Session Usage Table by Node

For each node, the Overall Session Usage Table by Node (Figure 2-20) presents a bar graph showing the total number of connected sessions and consumed threads by each node.

Figure 2-20 Overall Session Usage by Node

Text description of the illustration 2sesnode.gif

Overall Session Usage Table by Host

For each host, the Overall Session Usage Table by Host (Figure 2-21) presents a bar graph showing the total number of connected sessions and consumed threads by each host.

Figure 2-21 Overall Session Usage by Host

Text description of the illustration 2seshost.gif

Overall Memory Usage Table by Node

For each node, the Overall Memory Usage Table by Node (Figure 2-22) presents a bar graph showing the total amount of memory consumed by each node. Multiple data points will be illustrated if present.

Figure 2-22 Overall Memory Usage by Node

Text description of the illustration 2memnode.gif

Overall Memory Usage Table by Host

For each host, the Overall Memory Usage Table by Host (Figure 2-23) presents a bar graph showing the total amount of memory consumed by each host. Multiple data points will be illustrated if present.

Figure 2-23 Overall Memory Usage by Host

Text description of the illustration 2memhost.gif

Monitoring Node Properties

You can also view the properties of a particular Oracle 9iFS node.

On the Oracle 9iFS Node page, click the Node Performance & Statistics link.

Figure 2-24 Node Properties

Text description of the illustration 2nodperf.gif

Log Files

Log files are generated by the domain controller and each node.

• The domain controller log (DomainController.log) records major state transitions of its nodes; for example, started, failed, or restarted, and provides centralized data on overall domain health.

• The node log (Node.log) records the same type of information for the nodes. All errors are logged with stack traces. Log files are located in:

  $ORACLE_HOME/9ifs/log
  
  

You can set various options for these log files; for example, whether to overwrite the log each time the domain is started. These options are set in the DomainController.def and Node.def files, described in Appendix D, "Process Configuration Files".

Log files are also generated for the Oracle Enterprise Manager Java Console, the Oracle 9iFS Manager, and the dashboard.

• $ORACLE_HOME/9ifs/log/ifsmgr.log contains information for both Oracle Enterprise Manager Java Console and Oracle 9iFS Manager. You can set options for the ifsmgr.log file in:

  $ORACLE_HOME/9ifs/settings/IfsManager.def
  

• $ORACLE_HOME/9ifs/log/dashboard.log contains information from the dashboard. No settings for the dashboard log may be modified.

Log files for the Oracle Enterprise Manager Console for Oracle9iAS are located under $ORACLE_HOME/sysman/log and include:

• em-servlet.log

• emd.log (Oracle 9iFS logging messages will show up in this log.)

• em.log

You can set options for those log files by changing $ORACLE_HOME/sysman/config/logging.properties. For example, if you want to view detailed Oracle 9iFS exception stack trace in emd.log, you insert the following lines:

log4j.category.oracle.ifs.clients.webadmin=DEBUG, emdAppender log4j.additivity.oracle.ifs.clients.webadmin=false

into the section started with:

# category properties for logging by class name.