3 General Node Manager Configuration

This chapter describes a Node Manager configuration process and the general procedures that are applicable to both the Java and script-based version of Node Manager.

This chapter includes the following sections:

Overview of Node Manager Configuration

This section describes general Node Manager configuration steps that apply to the Java and script version of Node Manager. After you have performed the general Node Manager configuration, you should perform the configuration procedures outlined in Chapter 4, "Configuring Java Node Manager" or Chapter 5, "Configuring Script Node Manager" depending on which version of Node Manager you are using.

In this release, the Java-based version of Node Manager has a simplified, out-of-the-box configuration. For more information, see Default Node Manager Configuration.

Controlling and Configuring Node Manager Using WLST

The WebLogic Scripting Tool (WLST) is a command-line scripting interface that system administrators and operators use to monitor and manage WebLogic Server instances and domains. You can start, stop, and restart server instances remotely or locally, using WLST as a Node Manager client. In addition, WLST can obtain server status and retrieve the contents of the server output log and Node Manager log. For more information on WLST Node Manager commands, see "WLST Command and Variable Reference" in WLST Command Reference for WebLogic Server.

Step 1: Configure Your Computer to Run Node Manager

Node Manager must run on each computer that hosts a WebLogic Server instance that you want to control with Node Manager. Ideally, Node Manager should run as an operating system service or daemon, so that it is automatically restarted in the event of system failure or reboot.

By default, the operating system service starts up Node Manager to listen on localhost:5556. If you want Node Manager to accept commands from remote systems, you must edit the script to listen on a non-localhost listen address. For more information, see Running Node Manager as a Startup Service.

Note:

On UNIX platforms, Oracle does not recommend running Node Manager as the root user. However, to achieve Post-Bind GID, you must start Node Manager as the root user. Post-Bind GID enables a server running on your machine to bind to a UNIX group ID (GID) after it finishes all privileged startup actions.

Step 2: Specify Node Manager User Name and Password

The nm_password.properties file contains the Node Manager user name and password. These are used to authenticate connection between a client (for example, the Administration Server) and Node Manager.

Note:

This user name and password are only used to authenticate connections between Node Manager and clients. They are independent from the server administration ID and password.

This file is created for you when you use nmEnroll to copy the necessary configurations files from one machine to another when creating a domain or when using the Configuration Wizard. The file is located in DOMAIN_HOME/config/nodemanager, where DOMAIN_HOME is the location of your WebLogic domain, typically, ORACLE_HOME\user_projects\domains\domain_name.

The Configuration Wizard prompts for a Node Manager user name and password for the initial configuration. This value is populated in the required file locally, however, in order to get it distributed remotely, you must use the nmEnroll command.

After nm_password.properties is created, you can change the values for the Node Manager password and properties using the Administration Console. Changes are propagated to the nm_password.properties file and are picked up by Node Manager.

You can use the following steps to alter Node Manager credentials:

  1. Start the Administration Server.

  2. Using the Administration Console, update the Node Manager credentials using the Advanced options under domain_name > Security > General.

  3. Invoke WLST and connect to an Administration Server using the connect command. See "Using the WebLogic Scripting Tool" in Understanding the WebLogic Scripting Tool.

  4. Run nmEnroll using the following syntax:

    nmEnroll([domainDir], [nmHome])

    For example,

    nmEnroll('C:/oracle/user_projects/domains/prod_domain',
'C:/oracle/user_projects/domains/prod_domain/nodemanager')

    Running nmEnroll ensures that the correct Node Manager user and password token are supplied to each Managed Server.

    Note:

    You must run nmEnroll on each machine that is running a Managed Server. Additionally, you should run nmEnroll for each domain directory on each machine.

Note:

If you edit nm_password.properties manually (not recommended), you must restart Node Manager in order for the changes to take effect, whereas a restart is not required if you modify the values using the Administration Console with Node Manager running.

The nm_password.properties file must exist in the domain directory for each physical machine that runs Node Manager. If you change the domain's Node Manager user name and password, you should run nmEnroll on each machine to synchronize the nm_password.properties file. If you configure multiple domains on a machine, each domain can use a different Node Manager user name and password.

Step 3: Configure a Machine to Use Node Manager

A WebLogic Server machine resource associates a particular machine with the server instances it hosts, and specifies the connection attributes for a Node Manager process on that system.

Configure a machine definition for each machine that runs a Node Manager process using the Environment > Machines > machine_name > Node Manager page in the Administration Console. Enter the following values:

  1. The DNS name or IP address upon which Node Manager listens in the Listen Address field.

  2. The port number in the Listen Port field. Note that specifying the port number is especially important if you have modified it from the default value.

Note:

The listen address you specify must match exactly the host name appearing in the CN component of the Node Manager SSL server digital certificate subject DN.

After configuring each computer as a machine resource, you must assign each server instance that you will control with Node Manager to the machine upon which it runs.

  1. In the Administration Console, select Environment > Servers > server_name > Configuration > General.

  2. In the Machine field, select the machine to which you want to assign the server.

Note:

You cannot change the machine of the Administration Server using the Administration Console. You cannot change the cluster or machine of a running server.

Step 4: Configuring nodemanager.domains File

The nodemanager.domains file specifies the domains that a Node Manager instance controls. Thus standalone clients do not need to specify the domain directory explicitly.

This file must contain an entry specifying the domain directory for each domain a Node Manager instance controls, in this form:

domain-name=domain-directory

When a user issues a command for a domain, Node Manager looks up the domain directory from nodemanager.domains.

This file provides additional security by restricting Node Manager client access to the domains listed in this file. The client can only execute commands for the domains listed in nodemanager.domains.

For the Java-based Node Manager, this file is typically located under ORACLE_HOME\user_projects\domains\domain_name\nodemanager. For the script-based Node Manager, this file's default location is WL_HOME/common/nodemanager, where WL_HOME is the location in which you installed WebLogic Server, for example, ORACLE_HOME/wlserver.

If you created your domain with the Configuration Wizard, the nodemanager.domains file was created for you. However, in this release of WebLogic Server, if you are using the script version of Node Manager, you must create or copy into NodeManagerHome, a nodemanager.domains file that specifies the domains that you want a Node Manager instance to control. Alternatively, you can register WebLogic domains with the script-based Node Manager using the WLST command, nmEnroll.

If instead of a per domain Node Manager, you want to configure a per host Node Manager, you must manually create or copy a nodemanager.domains file under ORACLE_HOME\oracle_common\common\nodemanager, the per host NodeManagerHome location. For more information, see Default Node Manager Configuration.

If necessary, you can manually edit nodemanager.domains to add domains.

Note:

If you use the backslash character (\) in nodemanager.domains, you must escape it as (\\).

Example 3-1 nodemanager.domains File

#Domains and directories created by Configuration Wizard
#Mon Jan 07 10:57:18 EST 2013
base_domain=C\:\\Oracle\\Middleware\\Oracle_Home\\user_projects\\domains\\base_domain
prod_domain=C\:\\Oracle\\Middleware\\Oracle_Home\\user_projects\\domains\\prod_domain

Step 5: Configuring Remote Startup Arguments

In the Administration Console, on the Server > Configuration > Server Start page for the Managed Server, specify the startup arguments that Node Manager will use to start a Managed Server. If you do not specify startup arguments for a Managed Server, Node Manager uses its own properties as defaults to start the Managed Server. For more information, see Reviewing nodemanager.properties. Although these defaults are sufficient to boot a Managed Server, to ensure a consistent and reliable boot process, configure startup arguments for each Managed Server instance. The specified startup arguments are used for starting Managed Servers only. They will not be used by an Administration Server instance that is started by Node Manager.

If you will run Node Manager as a Windows service, as described in Running Node Manager as a Startup Service, you must configure the -Xrs JVM property for each Managed Server that will be under Node Manager control.

If you do not set this option, Node Manager will not be able to restart a Managed Server after a system reboot, due to this sequence of events:

  1. A reboot causes a running Managed Server to be killed before Node Manager and Administration Server operating system services are shut down.

  2. During the interval between the Managed Server being killed, and a Node Manager service being shut down, Node Manager continues to monitor the Managed Server, detects that it was killed, and attempts to restart it.

  3. The operating system does not allow restart of the Managed Server because the machine is shutting down.

  4. Node Manager marks the Managed Server as failed, and it will not start this server when the machine comes up again.

Starting a Managed Server with the -Xrs or -Xnohup option avoids this sequence of events by preventing the immediate shutdown of the Managed Server during machine shutdown.

Step 6: Setting Server Startup Properties

You can use Node Manager to set the startup properties for a server. These properties can be defined in startup.properties or passed as an object using administrative utilities such as WLST. The methods of setting startup properties and their valid values are outlined in the sections below.

startup.properties

Node Manager uses the startup.properties file to determine the startup configuration when starting a server. This file is defined for each server instance and is located in DOMAIN_HOME/servers/server_name/data/nodemanager/startup.properties.

The contents of startup.properties are derived from the Server MBean, or the Cluster MBean if the server is part of a cluster. For more information, see the MBean Reference for Oracle WebLogic Server.

Setting Startup Properties Using WLST

When using the WLST nmStart command, the server configuration cannot be determined directly. Therefore, you must pass the server start properties as a WLST properties object to the nmStart command.

Server Startup Properties

The following server startup properties can be passed to a server when started using Node Manager.

Table 3-1 Server Startup Properties

Property Description

JavaHome

Defines the Java home directory used when starting the server.

Arguments

The arguments used when starting the server.

SSLArguments

These arguments are used when you have enabled the domain-wide administration port.

RestartInterval

The amount of time Node Manager will spend attempting to restart a failed server. Within this period of time Node Manager will attempt to restart the failed server up to the number defined by RestartMax. By default, Node Manager will attempt to restart a server indefinitely until the FAILED_NOT_RESTARTABLE state is reached.

RestartMax

The number of times Node Manager will attempt to restart a failed server within the interval defined by RestartInterval. RestarMax is only recognized if RestartInterval is defined.

RestartDelaySeconds

The number of seconds Node Manager should wait before attempting to restart the server.

ClassPath

The classpath to use when starting a server.

OracleHome

The Oracle home directory to use when starting a server.

AdminURL

The URL of the Administration Server.

Note: This value should only be specified in the startup.properties file for a Managed Server.

AutoRestart

Specifies whether Node Manager can automatically restart this server if it fails.

Note: The CrashRecoveryEnabled configuration property takes precedence over the AutoRestart property in a crash recovery scenario. For example, if a server instance has AutoRestart=false but CrashRecoveryEnabled=true, when Node Manager restarts, Node Manager tries to recover the server instance if the server failed when Node Manager was not running.

AutoKillIfFailed

Specifies whether Node Manager should automatically kill the server if its health status is failed.

SecurityPolicyFile

Specifies the security policy file to use when starting this server.

ServerIP

The IP address of the server.

Step 7: Define the Administration Server Address

Make sure that a listen address is defined for each Administration Server that will connect to a Node Manager process. If the listen address for an Administration Server is not defined, when Node Manager starts a Managed Server it will direct the Managed Server to contact localhost for its configuration information.

Set the Listen Address using the Servers > Configuration > General page in the Administration Console.

Step 8: (Optional) Set Node Manager Environment Variables

By default, you need not set any additional environment variables before starting Node Manager. The sample Node Manager start scripts and install service scripts provided with WebLogic Server set the required variables and start Node Manager listening on the default address, localhost.

To start Node Manager listening on a non-default address, you can use one of the following methods:

  • Edit the nodemanager.properties file.

    Set the LISTEN_ADDRESS variable to <host> and the LISTEN_PORT variable to <port> before calling the startNodeManager script. See Reviewing nodemanager.properties.

  • Set the values when executing the startNodeManager script.

    The startNodeManager scripts will set the first two positional parameters to LISTEN_ADDRESS and LISTEN_PORT when entered on the command line.

    For example, enter this command to start Node Manager on host llama and port 7777:

    startNodeManager.cmd llama 7777 (Windows)
sh startNodeManager.sh llama 7777 (UNIX)

    Enter this command to start Node Manager on host llama:

    startNodeManager.cmd llama (Windows)
sh startNodeManager.sh llama (UNIX)

Configuring a non-default listening address for Node Manager is most useful in production environments so that traffic from other machines can potentially reach it. Also, if you have a multihomed machine or a machine with multiple network interface cards, Node Manager can be listening on any one of the addresses on the machine.

Table 3-2 Node Manager Environment Variables

Environment Variable Description 
JAVA_HOME

JDK root directory used by Node Manager. For example:

set JAVA_HOME=c:\jdk1.7.0_06

Node Manager has the same JDK version requirements as WebLogic Server.

 
WL_HOME

WebLogic Server installation directory. For example:

set WL_HOME=c:\Oracle\Middleware\Oracle_Home\wlserver

PATH

Must include the WebLogic Server bin directory and path to your Java executable. For example:

set PATH=%WL_HOME%\server\bin;%JAVA_HOME%\bin;%PATH%

LD_LIBRARY_PATH

(UNIX and Linux)

For Solaris systems, you must include the path to the native Node Manager libraries.

Solaris example:

LD_LIBRARY_PATH:$WL_HOME/server/lib/solaris:$WL_HOME/server/lib/solaris/oci816_8

Linux example:

LD_LIBRARY_PATH:$WL_HOME/server/native/linux:$WL_HOME/server/native/linux/i686

Note: Linux can be i686, ia64, or x86_64 architecture. The path would change to correspond with the appropriate architecture.

 
CLASSPATH

You can set the Node Manager CLASSPATH either as an option on the java command line used to start Node Manager, or as an environment variable.

Windows NT example:

set CLASSPATH=.;%WL_HOME%\server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\
weblogic.jar