Network Deployment (Distributed operating systems), v8.0 > Reference > Command-line utilities


addNode.sh


Overview

The addNode command incorporates an application server installation into a cell.

The node agent server is automatically started as part of addNode.sh unless you specify the option...

To start the node agent server...

Start node agents before starting any application servers.

When you run addNode.sh, the command stops the running application server that it is incorporating into a cell. We can optionally stop the application server before running addNode.sh.

Existing Windows services that are associated with servers before adding a node to a cell are removed when you run addNode.sh. If you remove the node from the cell later, Windows services are not automatically created again for the base servers. See information about the WASService command to create a Windows service for the product.

When you add a node, WAS might generate ports. The following items apply to port generation:

To ensure that the environment starts with the same version of the application, use option...

If any custom policy set is created on the server before you run addNode.sh, the custom policy set is not copied to the new cell. When using -installApps, an application on the server that uses the custom policy set fails to load the policy set after you run addNode.sh. To work around...

  1. Export the custom policy set from the stand-alone server
  2. Run addNode.sh
  3. Import the custom policy set to the new cell


addNode.sh syntax

addNode dmgr_host
       [dmgr_port]
       [-conntype type]
       [-includeapps]
       [-includebuses]
       [-startingport portnumber]
       [-portprops qualified_filename]
       [-nodeagentshortname name]
       [-nodegroupname name]
       [-registerservice]
       [-serviceusername name]
       [-servicepassword password]
       [-coregroupname name]
       [-noagent]
       [-statusport 1231]
       [-quiet]
       [-nowait]
       [-logfile filename]
       [-replacelog]
       [-trace]
       [-username uid]
       [-password pwd]
       [-localusername localuid]
       [-localpassword localpwd]
       [-profileName profilename]
       [-excludesecuritydomains true | false]
       [-asExistingNode]
       [-help]

The dmgr_host argument is required. All the other arguments are optional. The default port number is 8879 for the default SOAP port of the dmgr. SOAP is the default JMX connector type for the command. For multiple product installations or multiple profiles, the SOAP port might be different from 8879. Examine the dmgr SystemOut.log file to see the current ports in use.

With WAS v8 you can configure the server to use the HPEL log and trace infrastructure instead of using SystemOut.log, SystemErr.log, trace.log, and activity.log files or native z/OS logging facilities. You can access all log and trace information using $PROFILE/bin/LogViewer.sh.


addNode.sh parameters

-conntype <type>

JMX connector type to use for connecting to the dmgr. SOAP is the default JMX connector type for the command. Other valid types are JSR160RMI or RMI.

-includeapps

By default addNode.sh does not carry over applications from the stand-alone servers on the new node to the cell. In general, install applications using the dmgr. This option carries over the applications from a node. If the application already exists in the cell, then a warning is printed and the application does not install in the cell.

The applications are mapped to the server that you federated using addNode.sh. When addNode.sh operation completes, the applications run on that server when the server is started. Since these applications are part of the network deployment cell, you can map them to other servers and clusters in the cell using the administrative console.

Do not use the -includeapps option if the node to federate includes the product-supplied applications, such as the Samples. If you do, the second node to be federated that includes these applications is rejected because the applications exist in the cell and application merge is not supported.

If you use the -includeapps option on a node that includes a large number of applications, extend the administrative connector timeout to account for the additional time required to transfer all the applications to the dmgr. The -includeapps option is not a recommended approach unless only a few unique applications exist on the node, for example, with WebSphere Portal.

By default, during application installation, application binaries are extracted in...

WAS_HOME/installedApps/cellName
After addNode.sh, the cell name of the configuration on the node that you added changes from the base cell name to the dmgr cell name. The application binary files are located where they were before you ran addNode.sh, for example...

    WAS_HOME/installedApps/old_cellName

In the following example the application was installed by explicitly specifying the location for binary files:

    ${APP_INSTALL_ROOT}/${CELL}

The variable ${CELL}, specifies the current cell name. Then, when addNode.sh runs, the binary files are moved to...

    PROFILE_ROOT/installedApps/currentCellName

Federate the node to a cell using addNode.sh does not merge any cell-level configuration, including virtual host information. If the virtual host and aliases for the new cell do not match the product, you cannot access the applications running on the servers. You have to manually add all the virtual host and host aliases to the new cell, using the admin console running on the dmgr.

When the -includeapps parameter is specified, an OutOfMemoryError might occur if the JVM heap size is too small. When this error occurs, the following error message is issued:

    ADMU0111E: Program exiting with error: java.lang.OutOfMemoryError

This error can occur when large applications are processed, or when there is a large number of applications in the Base Application Server.

To recover from this error and successfully federate the application server, complete the following actions:

  1. Issue the cleanupNode command on your dmgr server.

  2. Increase the JVM heap size for the addNode script. When you issue addNode.sh, the JVM heap size is set to -Xms128m -Xmx512m.

    To increase these values, use the -javaoption parameter. For example...

      addNode.sh localhost 8879 -javaoption java_option "-Xmx512m"

  3. Reissue addNode.sh.

-includebuses

Copies the buses from the node to be federated to the cell. This parameter also attempts to copy the service integration bus configuration of the remote node into the cell. If the destination cell already contains a bus with the same name as any bus at the remote node, the add node fails.

To prevent this failure, you can act before using addNode.sh. We can delete the bus with that name in the destination cell, rename the bus to be added to the cell, or manually configure the bus already located in the cell.

-startingport <portNumber>

Supports the specification of a port number to use as the base port number for all node agent and JMS server ports created when addNode.sh runs. With this support you can control which ports are defined for these servers, rather than using the default port values. The starting port number is incremented one unit to calculate the port number for every node agent port and JMS server port configured during addNode.sh.

To avoid potential port conflicts, read about port number settings for more information about default port settings.

If multiple node agents exist on the same physical server, then you can define the base port number for each by using the -startingport parameter before federation, or by modifying the ports in the node agent section of serverindex.xml.

-portprops <filename>

Passes the name of the file that contains key-value pairs of explicit ports that you want the new node agent to use. For example, to set your SOAP and RMI ports to 3000 and 3001, create a file with the following two lines and pass it as the parameter:

    SOAP_CONNECTOR_ADDRESS=3000
    BOOTSTRAP_ADDRESS=3001

-nodeagentshortname <name>

The shortname to use for the new node agent.

-nodegroupname <name>

The name of the node group in which to add this node. If you do not specify, the node is added to the DefaultNodeGroup.

-registerservice

Registers the node agent as a Windows service.

We can optionally define a user name and password for the windows service using the -serviceusername parameter and the -servicepassword parameter. If you define a user name, give the user name Logon as a service authority for the service to run properly.

If you do not specify a user name and password, then the service runs under the local system account.

-serviceusername <user>

Use the given user name as the Windows service user.

-servicepassword <password>

Use the given Windows password as the Windows service password.

-coregroupname <name>

The name of the core group in which to add this node. If you do not specify this option, the node is added to the DefaultCoreGroup.

-noagent

Tells addNode.sh not to launch the node agent process for the new node.

-statusport

An optional parameter that allows an administrator to set the port number for node agent status callback. The tool opens this port and waits for status callback from the node agent indicating that the node agent has started. If the parameter is not set, an unused port is automatically allocated.

-quiet

Suppresses the progress information that addNode.sh prints in normal mode.

-nowait

Tells addNode.sh not to wait for successful initialization of the launched node agent process.

-logfile <filename>

Location of the log file to which trace information is written. By default, the log file is addNode.log and is created in the logs directory of the profile for the node being added.

-replacelog

Replaces the log file instead of appending to the current log file. By default, addNode.sh appends to the existing trace file. This option causes addNode.sh to overwrite the trace file.

-trace

Generates additional trace information in the log file for debugging purposes.

-user <name> or -username <name>

User name for authentication if security is enabled. Acts the same as the -user option. The user name that you choose must be a pre-existing user name.

-password <password>

Password for authentication if security is enabled. The password that you choose must be one that is associated with a pre-existing user name.

-localusername <name>

User name for authentication for existing application servers on the node to federate. This parameter is only applicable if security is enabled for the application server.

-localpassword <password>

Password for authentication for existing application servers on the node to federate. The password that you choose must be one that is associated with a pre-existing user name. This parameter is only applicable if security is enabled for the application server.

-profileName

Defines the profile of the Application Server process in a multi-profile installation. The -profileName option is not required for running in a single profile environment. The default for this option is the default profile. If you are adding a non-default profile to the dmgr cell, then this parameter is required.

-excludesecuritydomains true | false

Set to true if you do not want the security domains configured at the application server node federated into the cell. When true, the security configuration of the cell is used. This parameter applies only when we have security domains configured at the unfederated application server. By default, if there is a security domain associated with an application server, the security domain is federated to the cell so that the server uses the same security domain information after it is federated.

-asExistingNode

Recover an existing managed node of a dmgr cell.

Use to quickly recover a damaged node. For example, if a machine failure results in a unavailable node but node information remains on the dmgr, you can use the addNode -asExistingNode option to recreate the unavailable node by completing the following steps:

  1. Create a new profile with the same node and profile name as the unavailable node. We can create the profile on a different machine from the original node.

  2. For the new profile, run...

      addNode.sh ... -asExistingNode

We can also use the -asExistingNode option of addNode.sh to...

  • Move a node to a product installation on a different computer but at the same path
  • Move a node to a product installation on a different operating system or with a different path
  • Create cells from a template cell.

Other addNode options for node configuration are incompatible with this -asExistingNode option. Do not use -asExistingNode with the following incompatible options:

  • -includeapps
  • -includebuses
  • -startingport
  • -portprops
  • -nodeagentshortname
  • -nodegroupname
  • -registerservice
  • -serviceusername
  • -servicepassword
  • -coregroupname
  • -excludesecuritydomains

-help

Prints a usage statement.

-?

Prints a usage statement.


Usage scenario

The following examples demonstrate correct syntax:

The value 8879 is the default SOAP port.


Security considerations when adding an application server node to WAS ND cell

When adding a node to the cell, you automatically inherit both the user registry and the authentication mechanism of the cell.

For distributed security, all servers in the cell must use the same user registry and authentication mechanism.

To recover from a user registry change, modify the applications so that the user and group-to-role mappings are correct for the new user registry.

Another important consideration is the SSL public-key infrastructure. Before running addNode.sh with the dmgr, verify that addNode.sh can communicate as an SSL client with the dmgr. This communication requires that the addNode truststore that is configured in the sas.client.props file contains the signer certificate of the dmgr personal certificate, as found in the keystore and specified in the administrative console.

The following issues require consideration when running addNode.sh with security:


Related

addNode command best practices
Secure installation for client signer retrieval in SSL
Use command-line tools
Manage nodes
Recover or move nodes with the addNode -asExistingNode command
Map modules to servers
cleanupNode command
Assign users and groups to roles
Use HPEL to troubleshoot applications
removeNode command

+

Search Tips   |   Advanced Search