Skip Headers
Oracle® Fusion Middleware Node Manager Administrator's Guide for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E21050-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

4 Configuring Java Node Manager

This chapter describes how to configure the Java version of Node Manager.

This chapter includes the following sections:

Running Node Manager as a Service

Oracle recommends that you configure Node Manager to run as an operating system service or a Windows service on Windows systems. By default, the operating system service starts up Node Manager to listen on localhost:5556. For more information, see "About Installing Node Manager as a Windows Service" in the Installation Guide for Oracle WebLogic Server.

When you configure Node Manager to accept commands from remote systems, you must uninstall the default Node Manager service, then reinstall it to listen on a non-localhost listen address.

Depending on your platform, follow the instructions in Reconfigure Startup Service for Windows Installations or Configuring Java-based Node Manager Security

Reconfigure Startup Service for Windows Installations

The directory WL_HOME\server\bin (where WL_HOME is the top-level directory for the WebLogic Server installation) contains uninstallNodeMgrSvc.cmd, a script for uninstalling the Node Manager service, and installNodeMgrSvc.cmd, a script for installing Node Manager as a service.

  1. Delete the service using uninstallNodeMgrSvc.cmd.

  2. Edit installNodeMgrSvc.cmd to specify Node Manager's listen address and listen port.

    Make the same edits to uninstallNodeMgrSvc.cmd as you make to installNodeMgrSvc.cmd, so that you can successfully uninstall the service in the future, as desired.

  3. Run installNodeMgrSvc.cmd to re-install Node Manager as a service, listening on the updated address and port.

Configuring Java-based Node Manager Security

Node Manager security relies on a one-way SSL connection between the client and server.

If you are establishing a command-line connection to the Java Node Manager using the WebLogic Server Scripting Tool (WLST) nmConnect command, you provide the Node Manager user name and password. Node Manager verifies the user name and password against the domain nm_password.properties file. For more information on nm_password.properties, see Step 2: Specify Node Manager User Name and Password.

Node Manager credentials are located on the domain_name > Security > General > Advanced Options page in the Administration Console.

Administration Console users do not need to explicitly provide credentials to connect to Node Manager—the Node Manager user name and password are available in the domain configuration and are provided automatically.

Remote Server Start Security for Java-based Node Manager

A remote start user name and password is required to start a server instance with Node Manager. These credentials are provided differently for Administration Servers and Managed Servers.

  • Credentials for Managed Servers—When you invoke Node Manager to start a Managed Server it obtains its remote start user name and password from the Administration Server.

  • Credentials for Administration Servers—When you invoke Node Manager to start an Administration Server, the remote start user name and password can be provided in the following ways:

    • On the command line. See How Node Manager Starts an Administration Server.

    • From the Administration Server boot.properties file.

      The Configuration Wizard initializes the boot.properties file and the startup.properties file for an Administration Server when you create the domain.

    • Generated for you in a secure, encrypted way with the following steps:

      • Start the Administration Server with the flag -Dweblogic.nodemanager.ServiceEnabled=true.

      • Create the DOMAIN_HOME/servers/AdminServer/data/nodemanager directory.

      • Update any startup properties or the server's credentials while the both the Administration Server and the Node Manager are running.

Any server instance started by Node Manager encrypts and saves the credentials with which it started in a server-specific boot.properties file, for use in automatic restarts.

Reviewing nodemanager.properties

Node Manager properties define a variety of configuration settings for a Java-based Node Manager process. You can specify Node Manager properties on the command line or define them in the nodemanager.properties file, which is created in the directory where you start Node Manager the first time it starts up after installation of WebLogic Server. Values supplied on the command line override the values in nodemanager.properties.

nodemanager.properties is created in the directory specified in NodeManagerHome, where NodeManagerHome is WL_HOME/common/nodemanager. If NodeManagerHome is not defined, nodemanager.properties is created in the current directory.

Each time you start Node Manager, it looks for nodemanager.properties in the current directory, and creates the file if it does not exist in that directory. You cannot access the file until Node Manager has started up once.

Table 4-1 describes Node Manager properties.

In many environments, the SSL-related properties in nodemanager.properties may be the only Node Manager properties that you must explicitly define. However, nodemanager.properties also contains non-SSL properties in that you might need to specify, depending on your environment and preferences. For example:

Table 4-1 Node Manager Properties

Node Manager Property Description Default

PropertiesVersion

Specifies the version of the nodemanager.properties file. Do not change this value.

none

AuthenticationEnabled

If set to true, Node Manager authenticates the credentials against the domain.

true

LogFile

Location of the Node Manager log file.

NodeManagerHome/nodemanager.log

LogLimit

Maximum size of the Node Manager Log specified as an integer. When this limit is reached, a new log file is started.

unlimited

LogCount

Maximum number of log files to create when LogLimit is exceeded.

1

LogAppend

If set to true, then a new log file is not created when the Node Manager restarts; the existing log is appended instead.

true

LogToStderr

If set to true, the log output is also sent to the standard error output.

false

LogLevel

Severity level of logging used for the Node Manager log. Node Manager uses the standard logging levels from the java.util.logging.level package, http://download.oracle.com/javase/6/docs/api/java/util/logging/Level.html.

INFO

LogFormatter

Name of formatter class to use for NM log messages.

weblogic.nodemanager.server.LogFormatter

ListenBacklog

Maximum number of Node Manager backlog requests that the listener will accept. Additional incoming requests will be dropped until the backlogged requests are handled. Typically, you need not adjust this property.

50

CrashRecoveryEnabled

Enables system crash recovery.

false

SecureListener

If set to true, use the SSL listener, otherwise use the plain socket.

true

CipherSuite

The name of the cipher suite to use with the SSL listener.

TLS_RSA_EXPORT_WITH_RC4_40_MD5

StartScriptEnabled

If true, use the start script specified by StartScriptName to start a server. For more information, see Configuring Node Manager to Use Start and Stop Scripts.

true

StartScriptName

The name of the start script, located in the domain directory.

startWebLogic.sh (UNIX)

or

startWebLogic.cmd (Windows)

StopScriptEnabled

If true, execute the stop script specified by StopScriptName after the server has shutdown. For more information, see Configuring Node Manager to Use Start and Stop Scripts.

false

StopScriptName

The name of the script to be executed after server shutdown.

none

QuitEnabled

If set to true, allow the user to remotely stop the Node Manager.

WLST overrides the default value, false, when stopping Node Manager using the stopNodeManager() command.

false

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.

0

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.

NA

DomainsFile

The name of the nodemanager.domains file.

NodeManagerHome/nodemanager.domains

DomainsFileEnabled

If set to true, use the file specified in DomainsFile. If false, assumes the domain of the current directory or of WL_HOME.

true

StateCheckInterval

Specifies the interval Node Manager waits to perform a check of the server state.

500 milliseconds

CustomIdentityAlias

Specifies the alias when loading the private key into the keystore. This property is required when the Keystores property is set as CustomIdentityandCustomTrust or CustomIdentityAndJavaStandardTrust.

none

CustomIdentityKey

StoreFileName

Specifies the file name of the Identity keystore (meaning the keystore that contains the private key for the Node Manager). This property is required when the Keystores property is set as CustomIdentity and CustomTrust or CustomIdentityAndJavaStandardTrust.

none

CustomIdentity

KeyStorePassPhrase

Specifies the password defined when creating the Identity keystore. This field is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WebLogic Server only reads from the keystore, so whether or not you define this property depends on the requirements of the keystore.

none

CustomIdentity

KeyStoreType

Specifies the type of the Identity keystore. Generally, this is JKS. This property is optional.

default keystore type from java.security

CustomIdentity

PrivateKeyPassPhrase

Specifies the password used to retrieve the private key for WebLogic Server from the Identity keystore. This property is required when the Keystores property is set as CustomIdentityandCustomTrust or CustomIdentityAndJavaStandardTrust.

none

JavaHome

The Java home directory that Node Manager uses to start a Managed Servers on this machine, if the Managed Server does not have a Java home configured in its Remote Start page. If not specified in either place, Node Manager uses the Java home defined for the Node Manager process.

none

JavaStandardTrustKey

StorePassPhrase

Specifies the password defined when creating the Trust keystore. This field is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WebLogic Server only reads from the keystore, so whether or not you define this property depends on the requirements of the keystore.This property is required when the Keystores property is set as CustomIdentityandJavaStandard Trust or DemoIdentityAndDemoTrust.

none

KeyStores

Indicates the keystore configuration the Node Manager uses to find its identity (private key and digital certificate) and trust (trusted CA certificates). Possible values are:

  • DemoIdentityAndDemoTrust

    Use the demonstration Identity and Trust keystores located in the ORACLE_HOME\server\lib directory that are configured by default. The demonstration Trust keystore trusts all the certificate authorities in the Java Standard Trust keystore (JAVA_HOME\jre\lib\security\cacerts)

  • CustomIdentityAndJava

  • StandardTrust

    Uses a keystore you create, and the trusted CAs defined in the cacerts file in the JAVA_HOME\jre\lib\security\cacertsdirectory.

  • CustomIdentityAndCustomTrust

    Uses Identity and Trust keystores you create.

DemoIdentityAndDemoTrust

ListenAddress

Any address upon which the machine running Node Manager can listen for connection requests. This argument deprecates weblogic.nodemanager.listenAddress.

null

With this setting, Node Manager will listen on any IP address on the machine

ListenPort

The TCP port number on which Node Manager listens for connection requests. This argument deprecates weblogic.nodemanager.listenPort.

5556

NativeVersionEnabled

A value of true causes native libraries for the operating system to be used.

For UNIX systems other than Solaris, HP-UX, or Linux, set this property to false to run Node Manager in non-native mode. This will cause Node Manager to use the start script specified by the StartScriptEnabled property to start Managed Servers.

true

NodeManagerHome

Node Manager root directory which contains the following configuration and log files:

  • nm_data.properties

  • nodemanager.domains

  • nodemanager.log

  • nodemanager.properties

For more information on these files, see Node Manager Configuration and Log Files

Note: By default, NodeManagerHome is WL_HOME/common/nodemanager. In a production environment, you might want to customize the location of the Node Manager root directory.

NodeManagerHome

WebLogicHome

Root directory of the WebLogic Server installation. This is used as the default value of -Dweblogic.RootDirectory for a Managed Server that does not have a root directory configured in its Remote Start page. If not specified in either place, Node Manager starts the Managed Server in the directory where Node Manager runs.

none

keyFile

The path to the private key file to use for SSL communication with the Administration Server.

Note: This property is used only in the process of upgrading from WebLogic Server, Version 7.x to Version 9.x.

none

keyPassword

The password used to access the encrypted private key in the key file.

Note: This property is used only in the process of upgrading from WebLogic Server, Version 7.x to Version 9.x.

none

certificateFile

Specifies the path to the certificate file used for SSL authentication.

Note: This property is used only in the process of upgrading from WebLogic Server, Version 7.x to Version 9.x.

none

NetMask

The subnet mask for your network. For server migration, each Managed Server must use the same subnet mask to enable unicast and multicast communication among servers.

See also, the <InterfaceName> property for more flexibility entering multiple interfaces and corresponding netmask values.

none

Interface

The primary interface names used by migratable servers. For server migration, the primary interface names used by migratable servers must be the same.

See also, the <InterfaceName> property for more flexibility specifying multiple interfaces and a corresponding range of IP addresses that should be bound to a specific interface.

none

<InterfaceName>

An interface name along with a corresponding range of IP addresses and optional netmask value that should be bound to this specific network interface when migratable servers are started.

Syntax: <InterfaceName>=<IP_RANGE_MIN>-<IP_RANGE_MAX>,(optional) NetMask=<NETMASK_ADDRESS>

For example, the syntax for binding addresses 1 - 4 to interface eth0 and addresses 5 - 8 to bond0 is:

eth0=1-4,NetMask=255.255.255.0
bond0=5-8,NetMask=255.255.248.0

You can leave out the NetMask value, if desired, and simply enter:

eth0=200.10.10.1-200.10.10.255
bond0=199.0.0.1-199.0.0.255

The original NetMask and Interface properties are still supported and when specified, would apply to any address that is not already defined in an IP range.

For example, specifying these properties in the original format:

Interface=oldEth0
NetMask=255.255.255.0

Would be the same as specifying this in the new format:

oldEth0=*,Netmask=255.255.255.0

An asterisk (*) can be represent all IPs.

none

DomainsDirRemoteSharingEnabled

Specifies whether Node Manager is monitoring a shared domain directory. As such, more that one Node Manager may be monitoring the shared directory from different machines.

Set to true to indicate that you have a shared domain directory (mounted directory or Windows NFS) that multiple nodes will be sharing. Enabling this property allows multiple Node Managers to share the domain without affecting each other.

false

DomainRegistrationEnabled

By default, clients cannot dynamically register a new domain; domains must be configured during the domain creation process or before starting the Node Manager.

If set to true, clients can automatically register new domains, however, this creates a security risk, so it is not advised.

false

Deprecated Node Manager Properties

This section lists the Node Manager properties that are deprecated in WebLogic Server 9.x.

Note:

These properties are published for backwards compatibility and should not be used. SSL configurations will continue to work when migrating to WebLogic Server 9.x. However, the trusted key store is not used when running Node Manager.

Table 4-2 Deprecated Node Manager Properties

Node Manager Property Description Reason Deprecated

CustomTrustKeyPass

Phrase (Deprecated)

The password used to access the encrypted private key in the key file.

Using 1-way SSL, Node Manager does not need access to a trusted key store.

CustomTrustKeyStore

FileName(Deprecated)

Specifies the file name of the Trust keystore (meaning the keystore that contains the trusted CA certificates for the Node Manager). This property is required when the Keystores property is set as CustomIdentityandCustomTrust.

Using 1-way SSL, Node Manager does not need access to a trusted key store.

CustomTrustKeyStore

PassPhrase

(Deprecated)

Specifies the password defined when creating the Trust keystore. This field is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WebLogic Server only reads from the keystore, so whether or not you define this property depends on the requirements of the keystore.

Using 1-way SSL, Node Manager does not need access to a trusted key store.

CustomTrustKeyStore

Type (Deprecated)

Specifies the type of the Trust keystore. Generally, this is JKS. This property is optional.

Using 1-way SSL, Node Manager does not need access to a trusted key store.

JavaStandardTrustKey

StorePassPhrase

(Deprecated)

Specifies the password defined when creating the Trust keystore. This field is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WebLogic Server only reads from the keystore, so whether or not you define this property depends on the requirements of the keystore.This property is required when the Keystores property is set as CustomIdentityandJavaStandardTrust or DemoIdentityAndDemoTrust.

Using 1-way SSL, Node Manager does not need access to a trusted key store.


Configuring Node Manager to Use Start and Stop Scripts

You can configure Node Manager to use a script to start a Managed Server or to execute a script after server shutdown has completed. These scripts can be used to perform tasks that need to be performed before a server is started or after it is shutdown. Mounting and unmounting remote disks is one example of a task that can be performed using scripts.

Note:

Node Manager uses startup scripts to perform any required configuration, then start the server. In contrast, stop scripts are executed after the server has shutdown.

Script Location

Both the start and stop scripts should be placed in the following directory:

DOMAIN_HOME/bin/service_migration

Script execution should occur relative to this directory.

Best Practices When Using Start and Stop Scripts

When using start and stop scripts to control server behavior, Oracle recommends that you only edit the top line of the scripts that are provided. This ensures that all of the necessary environment variables are used during script execution.

Using Start Scripts

You can use a start script to specify required startup properties and perform any other work you need performed at start up. To define a start script:

  1. In the nodemanager.properties file, set the StartScriptEnabled property to true. (The default is true.) If your start script is named startWebLogic.sh or startWebLogic.cmd, Node Manager uses one of those scripts as the default.

  2. If you want to specify a custom start script, set the StartScriptName property to the name of your script in the nodemanager.properties file.

Node Manager sets the JAVA_VENDOR, JAVA_HOME, JAVA_OPTIONS, SECURITY_POLICY, CLASSPATH, and ADMIN_URL. It retrieves these values from the ServerMBean, ServerStartMBean, and SSLMBean when you use the Administration Console to start the server, or WLST connected to the Administration Server. When you use WLST connected directly to the Node Manager, you can specify the values; otherwise, they are left empty.

Node Manager combines all of the command line startup options (-D flags) that are specified in the ServerStartMBean Arguments attribute, as well as the SSLArguments into a single environmental variable called JAVA_OPTIONS. SSLArguments are retrieved from the values in the SSLMBean. The SSLMBean is inspected for ignoreHostnameVerification, HostnameVerifier, and ReverseDNSAllowed values, then those values are appended to the -D flags. All of those flags comprise the SSLArguments parameter. All of the values for SSLArguments as well as Arguments in the ServerStartMBean comprise the JAVA_OPTIONS environment variable that is defined for the start script. In addition, the script will append any of its own defined values onto this environment variable.

If there are resulting overlaps in this set of values, it will appear to the java command line like this:

java -Dflag1=value1 -Dflag1=value2 weblogic.Server

The java invocation will resolve the duplicate values.

Using Stop Scripts

You can use a stop script to perform any tasks that are required after the server has failed.

Note:

Stop scripts are used only to execute a script after a server fails and must be migrated.

To define a stop script:

  1. In the nodemanager.properties file, set the StopScriptEnabled property to true.

  2. Set the StopScriptName property to the name of your script in the nodemanager.properties file.

The following example shows a stop script that can be used to unmout a disk on UNIX systems:

#!/bin/sh
FS=/cluster/d2
if grep $FS /etc/mnttab > /dev/null 2>&1 ; then 
sync
   PIDS=`/usr/local/bin/lsof $FS | awk 
   '{if ($2 ~/[0-9]+/) { print $2} }' | sort -u`
kill -9 $PIDS
sleep 1
sync
   /usr/sbin/umount -f $FS
fi

Using SSL With Java-based Node Manager

Administration Servers and Managed Servers communicate with Java-based Node Manager using one-way SSL.

The default WebLogic Server installation includes demonstration Identity and Trust keystores that allow you to use SSL out of the box. The keystores, DemoIdentity.jks and DemoTrust.jks, are installed in WL_HOME/server/lib. For testing and development purposes, the keystore configuration is complete.

Configuring SSL for a production environment involves obtaining identity and trust for the Node Manager and each Administration Server and Managed Server with which the Node Manager will be communicating and then configuring the Node Manager, the Administration Server, and Managed Servers with the proper identity and trust. In addition, the use of host name verification and the Administration port must be taken into consideration. To configure production SSL components, see "Configuring SSL" in Securing Oracle WebLogic Server.

Configuring Node Manager on Multiple Machines

If you have a domain that has Managed Servers on multiple physical machines, you must ensure that Node Manager is installed and configured on each machine. You can use the WLST command nmEnroll to copy all of the required domain and configuration information from one machine to another. For more information, see Accessing Node Manager and nmEnroll in WebLogic Scripting Tool Command Reference.

Configuring Node Manager as an xinetd Service

When configuring Node Manager to run as an inetd or xinetd service, the following considerations apply:

The following example shows how Node Manager can be configured within xinetd:

# default: off
# description:nodemanager as a service
service nodemgrsvc
{
   type            = UNLISTED
   disable         = no
   socket_type     = stream
   protocol        = tcp
   wait            = yes
   user            = <username>
   port            = 5556
   flags           = NOLIBWRAP
   log_on_success += DURATION HOST USERID
   server          = <path-to-java>/java
   env             = CLASSPATH=<cp> LD_LIBRARY_PATH=<ldpath>
   server_args     = -client -DNodeManagerHome=<NMHome> <java options> 
   <nodemanager options> weblogic.NodeManager -v
}