addNode command


 

+

Search Tips   |   Advanced Search

 

Overview

The addNode command incorporates an appserver installation into a cell.

You must have Administrator privileges to use the addNode function.

Before starting, you might want to increase timeout in...

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

If we recycle the system that hosts an appserver node, and did not set up the node agent to act as an operating system daemon, issue a startNode command to start the node agent 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 prior to running addNode.sh.

Ports generated for the node agent are unique for all the profiles in the installation. We can create multiple profiles on the same installation and add them to one or more cells without concern for port conflicts.

To specify ports used by node agent, specify the ports in a file with the file name passed with the -portprops option. The format of the file is key=value pairs, one on each line, with the key being the same as the port name in serverindex.xml.

To use a number of sequential ports, then the -startingport option works the same as it does in V5.x. This means that port conflicts with other profiles are not be detected.

Existing Windows services that are associated with servers prior to adding a node to a cell are removed when you run addNode.sh. If we remove the node from the cell later, Windows services are not automatically created again for the base servers.

To create a Windows service for WAS ND, run WASService.

 

Syntax

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

The dmgr_host argument is required. All of 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. If we have multiple product installations or multiple profiles, the SOAP port might be different than 8879. Examine the dmgr SystemOut.log file to see the current ports in use.

 

Options available for addNode

-conntype <type>

JMX connector type to use for connecting to the deployment manager. Valid types are SOAP or Remote Method Invocation (RMI).

-excludesecuritydomains true | false

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

-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. The -includeapps option tells addNode.sh to carry 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.

Applications are mapped to the server being federated. 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, we can map them to other servers and clusters in the cell using the admin console.

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

If we use the -includeapps option on a node that includes a large number of applications, then the timeout for the administrative connector must be extended to account for the additional time required to transfer all of the applications to the dmgr during the addNode operation and to remotely install them into the cell. The -includeapps option is not a recommended approach unless only a few unique applications exist on the node.

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

APP_ROOT/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 deployment manager cell name. The application binary files are located where they were before you ran addNode.sh, for example...

APP_ROOT/installedApps/old_cellName

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

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

${$WAS_HOME}/currentCellName

Federating 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 WAS ND, we cannot access the applications running on the servers. we 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 appserver...

  1. Run cleanupNode.sh on the 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, we might specify the following (all on one line):

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

  3. Reissue addNode.sh.

-profileName

Defines the profile of the appserver 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 we are adding a non-default profile to the dmgr cell, then this parameter is required.

-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.

-nowait

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

-quiet

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

-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.

-trace

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

-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.

-noagent

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

-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.

-startingport <portNumber>

Supports the spec 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 we 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.

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

-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 we define a user name, give the user name Logon as a service authority for the service to run properly.

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

-statusport

Set 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.

-serviceusername <user>

Use the given user name as the Windows service user.

-servicepassword <password>

Use the given Windows password as the Windows service password.

-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 the 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

-coregroupname <name>

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

-nodegroupname <name>

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

-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, we can take actions 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.

-nodeagentshortname <name>

The shortname to use for the new node agent.

-localusername <name>

User name for authentication for existing appservers on the node to federate. This parameter is only applicable if security is enabled for the appserver.

-localpassword <password>

Password for authentication for existing appservers 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 appserver.

-help

Prints a usage statement.

-?

Prints a usage statement.

 

Usage scenario

The following examples demonstrate correct syntax:

addNode testhost 8879 (adds an appserver to the dmgr)
addNode deploymgr 8879 -trace (produces the addNode.log file)
addNode host25 8879 -nowait (does not wait for a node agent process)

The value 8879 is the default port.

 

Security considerations when adding an appserver node to 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. Prior to 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 configured in sas.client.props contains the signer certificate of the dmgr personal certificate, as found in the keystore and specified in the admin console.

When attempting to run system management commands such as addNode.sh, specify admin credentials to perform the operation. The addNode command accepts -username and -password parameters to specify the user ID and password, respectively. The user ID and password specified must be for an admin user. For example, specify a user that is a member of the console users with Administrator privileges or the administrative user ID configured in the user registry. See the following example of addNode.sh:

addNode CELL_HOST 8879 -includeapps -username user -password pass

The -includeapps parameter is optional. This option attempts to include the server applications into the Deployment Manager. The addNode command might fail if the user registries used by the application server and the dmgr are not the same. To correct this failure, either make the user registries the same or turn off security. If we change the user registries, remember to verify that the users-to-roles and groups-to-roles mappings are correct.

Add a secured remote node through the admin console is not supported.

We can either disable security on the remote node before performing the operation or perform the operation from the command prompt using addNode script.

Before running addNode.sh, verify that the truststore files on the nodes can communicate with the keystore files from the dmgr and vice versa.

When using the default DummyServerKeyFile and DummyServerTrustFile, no communication error occurs because these are already able to communicate. However, never use these dummy files in a production environment or anytime sensitive data is being transmitted.

If security is enabled for the V7.0 dmgr, then in order to federate a V6.x node the dmgr cannot use the auto-generated internal server ID.

The auto-generated internal server ID is used by default when enabling security.

When a client from a previous release tries to use addNode.sh to federate to a V7.0 dmgr, the client must first obtain signers for a successful handshake.

See on required changes before running addNode.sh in this scenario, read about obtaining signers from a previous release in the article on Secure installation for client retrieval, specifically the Obtaining signers for clients and servers from a previous release section.

The user registry can be changed by performing one of the following actions:

The server must be restarted for these changes to take effect.

After running addNode.sh, the appserver is in a new SSL domain.

It might contain SSL configurations that point to keystore and truststore files that are not prepared to interoperate with other servers in the same domain. Consider which servers are intercommunicating, and ensure that the servers are trusted within the truststore files.



Subtopics

addNode command best practices
Secure installation for client signer retrieval
Use command line tools
Manage nodes
Mapping modules to servers
cleanupNode
Assigning users and groups to roles
Port_number_settings_in_WAS790.html
removeNode