addNode command

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

Depending on the size and location of the new node you incorporate into the cell, this command can take a few minutes to complete.

You must have Administrator privileges to use the addNode function.

The node agent server is automatically started as part of the addNode command unless you specify the -noagent option. If you recycle the system that hosts an application server node, and did not set up the node agent to act as an operating system daemon, you must issue a startNode command to start the node agent before starting any application servers.

Restriction: You cannot add a Version 5.x node to an existing cell managed by a Version 6.x deployment manager. You can only include Version 5.x nodes in a Version 6.x mixed-release cell through migration. First, migrate the deployment manager from Version 5.x to Version 6.x; and then, either keep the nodes at Version 5.x or migrate them to Version 6.x.

Read the topic on using command line tools to determine whether to run the command from the profile or application server root directory.

Syntax

See the command syntax:

addNode dmgr_host [dmgr_port] [-profileName profilename]
[-conntype type] [-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 deployment manager. SOAP is the default Java Management Extensions (JMX) connector type for the command. If you have multiple product installations or multiple profiles, the SOAP port might be different than 8879. Examine the deployment manager SystemOut.log file to see the current ports in use.

Parameters

The following options are available for the addNode command:

-conntype <type>
Specifies the JMX connector type to use for connecting to the deployment manager. Valid types are SOAP or Remote Method Invocation (RMI).
-includeapps
By default the addNode command does not carry over applications from the stand-alone servers on the new node to the cell. In general, install applications using the deployment manager. The -includeapps option tells the addNode command 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.

The applications are mapped to the server that you federated using the addNode command. When the addNode command 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. Read about mapping modules to servers for more information.

Do not use the -includeapps option if the node that you want 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 already 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, 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 deployment manager 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 the app_server_root/installedApps/cellName directory. After the addNode command, 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 the addNode command, for example, app_server_root/installedApps/old_cellName.

In the following example the application was installed by explicitly specifying the location for binary files:
${app_server_root}/${CELL}
The variable ${CELL}, specifies the current cell name. Then, when the addNode command runs, the binary files are moved to the following directory:
${app_server_root}/currentCellName

Federating the node to a cell using the addNode command 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 administrative console running on the deployment manager.

Avoid trouble: When the -includeapps parameter is specified, an OutOfMemoryError might occur if the Java Virtual Machine (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.sh command on your deployment manager server. Read about the cleanupNode command for more information about this command.
  2. Increase the JVM heap size for the addNode script. When you issue the addNode.sh command, the JVM heap size is set to -Xms128m -Xmx512m. To increase these values, edit the JVM_EXTRA_CMD_ARGS variable in the config_root/bin/setupCmdLine.sh file of the Base Application Server being federated. For example, you might specify the following code (all on one line):

  3. Reissue the addNode.sh command.
gotcha
-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 deployment manager cell, then this parameter is required.
-user <name> or -username <name>
Specifies the 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 the addNode command not to wait for successful initialization of the launched node agent process.
-quiet
Suppresses the progress information that the addNode command prints in normal mode.
-logfile <filename>
Specifies the 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, the addNode command appends to the existing trace file. This option causes the addNode command to overwrite the trace file.
-noagent
Tells the addNode command not to launch the node agent process for the new node.
-password <password>
Specifies the 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 specification of a port number to use as the base port number for all node agent and Java Messaging Service (JMS) server ports created when the addNode command 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 the addNode command.

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 prior to federation, or by modifying the ports in the node agent section of the serverindex.xml file.

Registers the node agent as a Windows service.

You 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, you must 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.

-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.
-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 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
-coregroupname <name>
The name of the core group in which to add this node. If you 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 you 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, you can take actions before using the addNode command. You 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>
Specifies the user name for authentication for existing application servers on the node that you want to federate. This parameter is only applicable if security is enabled for the application server.
-localpassword <password>
Specifies the password for authentication for existing application servers on the node that you want 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.
-help
Prints a usage statement.
-?
Prints a usage statement.

Usage scenario

The following examples demonstrate correct syntax:
addNode testhost 8879 (adds an application server to the deployment manager)

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 application server node to Network Deployment cell

When adding a node to a cell, the newly federated node automatically inherits the user registry (Local OS, Lightweight Directory Access Protocol (LDAP), or Custom), authentication mechanism (LTPA or ICSF), and authorization setting (WebSphere bindings or System Authorization Facility (SAF) EJBROLE profiles) of the existing Network Deployment 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, you must modify your applications so that the user and group-to-role mappings are correct for the new user registry. See the article on assigning users and groups to roles.

Another important consideration is the Secure Sockets Layer (SSL) public-key infrastructure. Prior to running the addNode command with the deployment manager, verify that the addNode command can communicate as an SSL client with the deployment manager. This communication requires that the addNode truststore that is configured in the sas.client.props file contains the signer certificate of the deployment manager personal certificate, as found in the keystore and specified in the administrative console.

The following issues require consideration when running the addNode command with security:



Subtopics
addNode command best practices
Related tasks
Using command line tools
Managing nodes
Mapping modules to servers
cleanupNode command
Assigning users and groups to roles
Related information
removeNode command
addNode command
Reference topic    

Terms of Use | Feedback

Last updated: Sep 20, 2010 10:03:57 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=vela&product=was-nd-zos&topic=rxml_addnode
File name: rxml_addnode.html