5 Using Node Manager

Oracle recommends running WebLogic Servers Node Manager as a startup service. Use the recommended methods to start and stop the Java-based and script-based Node Manager.

This chapter includes the following topics:

Starting and Stopping Node Manager

Oracle WebLogic Server provides various methods for starting and stopping Node Manager.

This section includes the following topics:

Running Node Manager as a Startup Service

Node Manager must run on each computer that hosts an Oracle 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 a 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.

Oracle recommends that you install Node Manager to run as a startup service. This allows Node Manager to start up automatically each time the system is restarted. See Configuring Node Manager as an xinetd Service and Configuring Node Manager as an init.d 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 instance running on your machine to bind to a UNIX group ID (GID) after it finishes all privileged startup actions.

On Windows machines, use the following steps to install a per domain Node Manager Windows service:

  1. Log in to the machine with Administrator privileges.
  2. Open a DOS command prompt window.
  3. Change to the DOMAIN_HOME\bin directory.
  4. Enter the following command:
    installNodeMgrSvc.cmd
  5. After a few seconds, the following message is displayed:
    Oracle WebLogic <domain-name> NodeManager installed.

    The service is installed using the default Node Manager listen port (5556). If this listen port is already in use, the program prompts you to enter a different listen port.

Note:

If the Node Manager Windows service is already installed, the following message is displayed instead:
CreateService failed - The specified service already exists.

If you want to uninstall a per domain Node Manager Windows service, use the following steps:

  1. Log in to the machine with Administrator privileges.
  2. Open a DOS command prompt window.
  3. Change to the DOMAIN_HOME\bin directory.
  4. Enter the following command:
    uninstallNodeMgrSvc.cmd
  5. After a few seconds, the following message is displayed:
    Oracle WebLogic <domain-name> NodeManager removed.

By default, NODEMGR_HOST is set to localhost in installNodeMgrSvc.cmd, which means that Node Manager will listen only on the local host. If you do not want Node Manager listening on the local host, set NODEMGR_HOST to a valid hostname or IP address before installing the Node Manager service.

Note:

If you select to run a per host Node Manager as a Windows service, using WL_HOME\server\bin\installNodeMgrSvc.cmd, you must first perform the prerequisite configuration steps described in Configuring Per Host Node Manager.

Starting Java-Based Node Manager Using Scripts

Although running Node Manager as an operating system service is recommended, you can also start Node Manager manually at the command prompt or with a script. The environment variables Node Manager requires are described in Set Node Manager Environment Variables.

Sample start scripts for Node Manager are installed in each DOMAIN_HOME/bin and the WL_HOME\server\bin directory, where WL_HOME is the top-level installation directory for Oracle WebLogic Server. However, if you select to use the script in WL_HOME\server\bin, you must first perform the prerequisite steps described in Configuring Per Host Node Manager.

Use startNodeManager.cmd on Windows systems and startNodeManager.sh on UNIX systems.

The scripts set the required environment variables and start Node Manager in the appropriate NodeManagerHome directory. Node Manager uses this directory as a working directory for output and log files. To specify a different working directory, edit the start script with a text editor and set the value of the NODEMGR_HOME variable to the desired directory.

Command Syntax for Starting Java-Based Node Manager

The syntax for starting Java-based Node Manager is:

java [java_option=value ...] -D[nodemanager_property=value] -D[server_
property=value] weblogic.NodeManager

Where:

  • java_option is a direct argument to the java executable, such as -ms or -mx.

    Note:

    If you did not set the CLASSPATH environment variable, use the -classpath option to identify required Node Manager classes.
  • nodemanager_property is a Node Manager property. Instead of supplying Node Manager property values on the command line, you can edit the nodemanager.properties file, which is created in the NodeManagerHome directory. See Reviewing nodemanager.properties.

    Node Manager property values you supply on the command line override the values in nodemanager.properties.

  • server_property is a server-level property that Node Manager accepts on the command line, including:
    • bea.home: The BEA home directory that server instances on the current machine use.
    • java.security.policy: The path to the security policy file that server instances on the current machine use.

      Note:

      For UNIX systems:

      If you run Node Manager on a UNIX operating system other than Solaris, you cannot have any white space characters in any of the parameters that will be passed to the java command line when starting Node Manager. For example, this command fails due to the space character in the name "big iron".
      -Dweblogic.Name="big iron"

      For UNIX systems other than Solaris and Linux operating systems, you must disable the weblogic.nodemanager.nativeVersionEnabled option at the command line when starting Node Manager (or set the property in nodemanager.properties) to use the pure Java implementation. See Reviewing nodemanager.properties.

Running Script-Based Node Manager

Note:

In this release of Oracle WebLogic Server, prior to running the script-based implementation 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. See Configuring nodemanager.domains File. Alternatively, you can register WebLogic domains with Node Manager using the WLST command, nmEnroll.

If not specified, the default NodeManagerHome location is WL_HOME/common/nodemanager.

To use the SSH Node Manager Command Shell, start the Administration Server using the following command line option:
-Dweblogic.nodemanager.ShellCommand='ssh -o PasswordAuthentication=no %H wlscontrol.sh -d %D -r %R -s %S -x -c -f sample_custom_startscript.sh %C'

Note:

%C must be the last argument supplied to wlscontrol.sh.

The weblogic.nodemanager.ShellCommand attribute specifies the command template to use to communicate with a remote script-based Node Manager and execute Node Manager functions for server instances under its control.

The template assumes that wlscontrol.sh is in the default path on the remote machine hosting Node Manager.

The ShellCommand syntax is:
ssh -o PasswordAuthentication=no %H wlscontrol.sh -d %D -r %R -s %S %C'

The possible command line options are listed in Table 5-1. The possible parameter values are listed in Table 5-2.

For example, if you type the following command, the listen address and port of the SSH server default to the listen address and port used by Node Manager on the remote machine. The domain name and domain directory are assumed to be the root directory specified for the target server instance, myserver.
ssh -o PasswordAuthentication=no wlscontrol.sh myserver start
Th following command issues a START command to the server instance named ServerA, in the domain called ProductionDomain, located in the domains/ProductionDomain directory:
ssh -o PasswordAuthentication=no 172.11.111.11 wlscontrol.sh -d ProductionDomain
 -r ProductionDomain -s ServerA'

The ssh command must include the string:

-o PasswordAuthentication=no

This string passes the ssh PasswordAuthentication option. A value of yes causes the client to hang when it tries to read from the console.

Table 5-1 wlscontrol.sh Command Line Options

Parameter Description

-n

Specifies the Node Manager root directory.

-s

Specifies the server name.

-d

Specifies the domain name.

-r

Specifies the domain directory.

-c

Enables a server start script.

-f

The name of the server start script.

-p

The name of the server stop script.

-v

Enables verbose output.

-h

Prints the usage for wlscontrol.sh.

Table 5-2 Shell Command Templates

Parameter Description Default

%H

The host name of the SSH server.

NodeManagerMBean.ListenAddress

%N

The Node Manager home directory.

NodeManagerMBean.NodeManagerHome

%P

The port number of the SSH server.

NodeManagerMBean.ListenPort

22

%S

The Oracle WebLogic Server name.

none

%D

The Oracle WebLogic domain name.

none

%R

The domain directory (server root).

ServerStartMBean.RootDirectory

%C

The Node Manager script command:

  • START - Starts the server.
  • KILL - Kills the server.
  • STAT - Gets the server status.
  • GETLOG - Retrieves the server output log.
  • VERSION - The Return Node Manager version.

Note: This command must be the last element in the command.

none

Note:

If you notice that it takes a long time to start Node Manager or an Oracle WebLogic Server instance, it might be because of low entropy on your machine.

To check entropy:

cat /proc/sys/kernel/random/entropy_avail

Any result below 500 indicates that your system is at risk of running out of entropy. You can run rngd which replenishes random bytes to /dev/random using /dev/urandom as the source. Start rngd (as root). This command will ensure that your system does not run out of entropy:
$ rngd -r /dev/urandom -o /dev/random -b
You can configure the process by editing /etc/sysconfig/rngd with the following command:
EXTRA OPTIONS="-i -r /dev/urandom -o /dev/random -b -t 60 -W 2048"

Every 60 seconds, this will add bits to the entropy pool until the size is 2048. You can change the interval and size using the -t 60 and -W 2048 parameters.

You can refer to these blogs that describe this topic in detail:

Stopping Node Manager

To stop Node Manager, close the command shell in which it is running.

Alternatively, after having set the nodemanager.properties attribute QuitEnabled to true (the default is false), you can use WLST to connect to Node Manager and shut it down.
wls:/nm/mydomain> stopNodeManager()
Stopped Node Manager Process successfully
wls:/offline>

See stopNodeManager in the WLST Command Reference for Oracle WebLogic Server.

Stopping Java-Based Node Manager Using Scripts

The shutdown scripts for Node Manager are installed in the DOMAIN_HOME/bin and the WL_HOME/server/bin directories, where WL_HOME is the top-level installation directory for Oracle WebLogic Server.

These scripts require the NODEMGR_HOME variable to be set before execution. DOMAIN_HOME/bin/stopNodeManger.[cmd|sh] comes configured with the appropriate DOMAIN_HOME and NODEMGR_HOME values. However, before executing WL_HOME/stopNodemanager[.cmd|sh], you must define NODEMGR_HOME correctly.

To stop Node Manager, use stopNodeManager.cmd on Windows systems and stopNodeManager.sh on UNIX systems.

Using Node Manager to Control Servers

Oracle recommends to use the WebLogic Scripting Tool and Node Manager to start and stop the Administration Server and Managed Servers.

Use the recommended procedures to start and stop server instances. See Using WLST and Node Manager to Manage Servers in Understanding the WebLogic Scripting Tool and Node Manager Commands in WLST Command Reference for Oracle WebLogic Server.

For information about changing the credentials used for starting and stopping Oracle WebLogic Server instances, see Changing the Credentials Used for Starting a Server in Administering Server Startup and Shutdown for Oracle WebLogic Server.

This section includes the following topics:

Starting the Administration Server Using Node Manager

The following general procedures are recommended for starting an Administration Server using WLST and Node Manager.

Establish startup information using the nmGenBootStartupProps command. This command generates the Node Manager property files boot.properties and startup.properties.

You must complete all of the following steps when starting the Administration Server for the first time in your domain, or if you make any configuration changes to the Administration Server.

For subsequent startups of the Administration Server, go to Step 7 to start the Administration Server directly with Node Manager.

  1. Start the Administration Server manually by performing one of the following actions:
    • Run the startWebLogic script from the DOMAIN_HOME/bin directory, where DOMAIN_HOME represents the directory in which your Oracle WebLogic Server domain is configured.
    • Invoke WLST and use the WLST startServer command to start the Administration Server.
  2. (optional) Add any additional configuration information for the Administration Server.
  3. Invoke WLST, if not already running.

    On Windows, you can use a shortcut on the Start menu to set your environment variables and invoke WLST.

  4. Connect WLST to the Administration Server instance using the connect command.
  5. Establish startup information using the nmGenBootStartupProps command. This command generates the Node Manager property files boot.properties and startup.properties.
  6. Shut down the Administration Server, which also disconnects WLST.
  7. Start Node Manager. See Starting and Stopping Node Manager.
  8. Invoke WLST. See Invoking WLST in Understanding the WebLogic Scripting Tool.
  9. Connect WLST to Node Manager using the nmConnect command.
  10. Start the Administration Server using the nmStart command.
    The following example starts the Administration Server in the specified WebLogic domain using Node Manager. In this example, the prps variable stores the system property settings and is passed to the command using the props argument.
    wls:/nm/mydomain> prps = makePropertiesObject("AdminURL=http://
    listen_address;listen_port;Username=username;Password=password
    ;weblogic.ListenPort=8001")
    wls:/nm/mydomain> nmStart("AdminServer",props=prps)
    Starting server AdminServer...
    Server AdminServer started successfully
    wls:/nm/mydomain>

After the Administration Server has been started, you can use WLST to start the Managed Servers in your domain.

Note:

Starting the server instance using the nmStart command allows Node Manager to monitor the state of your Administration Server and restart it in case of failure. Node Manager can only restart server instances that were started in this way.

Using nmStart allows you to pass specific properties to a server instance, but should only be used for debugging. Server properties passed through nmStart are not preserved the next time the server instance is restarted.

Starting Managed Servers Using WLST

The following general procedures are recommended for starting a Managed Server using WLST and Node Manager.

  1. Start Node Manager. See Starting and Stopping Node Manager.
  2. Start an Administration Server. See Starting an Administration Server with a Startup Script in Administering Server Startup and Shutdown for Oracle WebLogic Server.
  3. Invoke WLST and connect to an Administration Server using the connect command. See Invoke WLST.
  4. Start the Managed Server using the WLST start command.

Using the start command causes WLST to contact the Administration Server to determine the Managed Servers startup properties. These are in turn passed to Node Manager and are used to start the Managed Server.

Starting Managed Servers Using the Administration Console

The following general procedures are recommended for starting a Managed Server using the Oracle WebLogic Server Administration Console:

  1. If you have not already done so, create a Managed Server.
  2. Node Manager must run on each computer that hosts Oracle WebLogic Server instances that you want to control with Node Manager. Configure each computer as a machine in Oracle WebLogic Server. See Configuring a Machine to Use Node Manager.
  3. Assign each server instance that you will control with Node Manager to the machine on which it runs. See Assigning Server Instances to a Machine.
  4. Start Node Manager on the computer that you want to host the Managed Server. The Oracle WebLogic Server custom installation process optionally installs and starts Node Manager as a Windows service on Windows systems. If it's not already running, you can start Node Manager manually at a command prompt or with a script.

See Start Managed Servers from the Administration Console in Oracle WebLogic Server Administration Console Online Help.

Configuring a Machine to Use Node Manager

An Oracle 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 Node Manager page in the WebLogic Server Administration Console. To access this page, expand Environment, click Machines, select machine_name, and then click Node Manager.

  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 Node Manager Listen Address value reflects the client-side configuration. It tells the Administration Server or clients on the Administration Server how to connect to Node Manager. This attribute does not configure Node Manager.

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.

Assigning Server Instances to a Machine

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

  1. In the WebLogic Server Administration Console, select Environment, click Servers, select server_name, select Configuration, and then click General.
  2. In the Machine field, select the machine to which you want to assign the server instance.

Note:

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

Starting Managed Servers without an Administration Server

The following general procedures are recommended for starting a Managed Server using WLST and Node Manager if you do not want to use the Administration Server to determine a Managed Server's startup properties:

  1. Start Node Manager. See Starting and Stopping Node Manager.
  2. Invoke WLST and connect to Node Manager using the nmConnect command.
  3. Start the Managed Server using the WLST nmStart command.

    Note:

    If you use the default security providers, the first time you start a Managed Server instance, it must be able to contact the Administration Server.

    To start a Managed Server in MSI mode when the Administration Server is down, you must use WLST to connect directly to Node Manager.

Using the nmStart command allows you to restart a Managed Server without the Administration Server and to specify the server startup properties you want. However, the following considerations apply:

  • In order to start a server instance with nmStart, you must ensure that boot.properties and startup.properties are already defined.

  • nmStart should not be used to permanently change the startup properties for a server instance. The next time a server instance is migrated or restarted from the Administration Server, these properties will not be used.

  • When passing the server instance user name and password using nmStart, these values are not encrypted.

The following example starts the managed1 server in the current WebLogic domain using Node Manager:
wls:/nm/mydomain> nmStart("managed1")
Starting server managed1 ...
Server managed1 started successfully
wls:/nm/mydomain>