addNode.sh command

The addNode.sh command incorporates an application server installation into a cell. A nodeagent process is automatically started as part of the addNode.sh command unless we specify the -noagent option. Depending on the size and location of the new node you incorporate into the cell, this command can take a few minutes to complete. The addNode.sh command stops the running application server that it is incorporating into a cell.

Ports generated for the node agent are unique for all the profiles in the installation. For development purposes, we can create multiple profiles on the same installation and add them to one or more cells without concern for port conflicts. To specify the ports used by the nodeagent, specify ports in a file portsFile.txt, and specify that file using 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, consider the -startingport option. This means that port conflicts with other profiles are not detected.

Custom policy sets are not copied to the new cell after we run the addNode.sh command. Use the -includeapps option to ensure the environment starts with the same version of the application.

Start node agents before starting any application servers...

/profile_home/bin/startNode.sh

Syntax

addNode.sh 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 deployment manager. 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 from 8879. Examine the deployment manager SystemOut.log file to see the current ports in use.

Parameters

The following options are available for the addNode.sh command:

-conntype <type>

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

-includeapps

By default the addNode.sh 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.sh 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 we federated using the addNode.sh command. When the addNode.sh command 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 administrative console.

Do not use the -includeapps option if the node to federate includes the product-supplied applications, such as the Samples. If we 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 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 the applications to the deployment manager during the addNode.sh 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.

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

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:

1. Issue the cleanupNode command on the deployment manager server. Read about the cleanupNode command for more information about this command.

2. Increase the JVM heap size for the addNode.sh script. When we issue the addNode.sh command, 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 the addNode.sh command.

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

app_server_root/installedApps/cellName

After the addNode.sh command, the cell name of the configuration on the node that we added changes from the base cell name to the deployment manager cell name. The application binary files are located where they were before we ran the addNode.sh 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_INSTALL_ROOT}/${CELL}

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

profile_root/installedApps/currentCellName

-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 act before using the addNode.sh command. 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>

Specify base port number for all node agent and JMS server ports created when the addNode.sh command runs. 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.sh command. Alternatively, we can modify ports in the node agent section of serverindex.xml.

-portprops <filename>

Pass the name of the file containing key-value pairs of explicit ports that we 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 we do not specify, the node is added to the DefaultNodeGroup.

(Windows) -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, we must 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.

(Windows) -serviceusername <user>

(Windows) Use the given user name as the Windows service user.

(Windows) -servicepassword <password>

(Windows) 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 we do not specify this option, the node is added to the DefaultCoreGroup.

-noagent

Tells the addNode.sh command 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 the addNode.sh command prints in normal mode.

-nowait

Tells the addNode.sh command 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

Replace the log file instead of appending to the current log file. By default, the addNode.sh command appends to the existing trace file. This option causes the addNode.sh command 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 chosen must be a pre-existing user name.

-password <password>

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

-localusername <name>

User name for authentication for existing application servers on the node to federate. 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 chosen must be one associated with a pre-existing user name. 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 we are adding a non-default profile to the deployment manager cell, then this parameter is required.

-excludesecuritydomains true | false

Set the -excludesecuritydomains parameter to true if we do not want the security domains configured at the application server 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 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 deployment manager cell.

Use the -asExistingNode parameter of the addNode.sh command to quickly recover a damaged node. For example, if a machine failure results in a unavailable node but node information remains on the deployment manager, we can use the addNode.sh -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. Create the profile on a different machine from the original node.

2. For the new profile, run the addNode.sh command with the -asExistingNode option.

We can also use the -asExistingNode option of the addNode.sh command to move a node to a product installation on a different computer but at the same path, to move a node to a product installation on a different operating system or with a different path, or to create cells from a template cell. See the topic on recovering or moving nodes with the addNode.sh -asExistingNode command.

Other addNode.sh 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, or -excludesecuritydomains.

-help

Prints a usage statement.

-?

Prints a usage statement.

Usage scenario

Add an application server to the deployment manager...

addNode.sh testhost 8879 -includeapps -username user -password pass

Produce the addNode.log file

addNode.sh deploymgr 8879 -trace

Do not wait for a node agent process...

addNode.sh host25 8879 -nowait

The value 8879 is the default port.

Add profile, mynode, to the cell managed by profile mydmgr, which listens on SOAP port 11383

addNode.sh mydmgr 11383 -profileName mynode

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, we must modify the 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 SSL public-key infrastructure. Before running the addNode.sh command with the deployment manager, verify that the addNode.sh command can communicate as an SSL client with the deployment manager. This communication requires that the addNode.sh truststore 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.sh command with security:

• When attempting to run system management commands such as the addNode.sh command, specify administrative credentials to perform the operation. The addNode.sh command accepts -username and -password parameters to specify the user ID and password. The user ID and password specified must be for an administrative 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 the addNode.sh command:
  addNode.sh 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.sh command might fail if the user registries used by the application server and the deployment manager 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. Read about the addNode.sh command for more information about the addNode.sh syntax.

• Add a secured remote node through the administrative 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 the addNode.sh script.

• Before running the addNode.sh command, verify that the truststore files on the nodes communicate with the keystore files and System Authorization Facility (SAF) keyring that is owned by the deployment manager and vice versa. If we generate certificates for the deployment manager using the same certificate authority as we used for the node agent process, then we are successful. The following SSL configurations must contain keystores and truststores that can interoperate:

  • System SSL repertoire specified in the administrative console. Click System administration > Deployment manager > HTTP transports > sslportno > SSL.

  • SSL repertoire for appropriate JMX connector if SOAP is specified. Click System administration > Deployment manager > Administration Services > JMX Connectors > SOAPConnector > Custom properties > sslConfig.

  • SSL repertoire specified in NodeAgent. Click System Administration > Node agents > NodeAgent Server > Administration Services > JMX Connectors > SOAPConnector > Custom properties > sslConfig.

• If security is enabled for the v7 or 8 deployment manager, the deployment manager cannot use the auto-generated internal server ID to federate a v6.x node. The auto-generated internal server ID is used by default when enabling security.

• When a client from a previous release tries to use the addNode.sh command to federate to a Version 7 or 8 deployment manager, the client must first obtain signers for a successful handshake. For more information about required changes before running the addNode.sh command in this scenario, read about obtaining signers from a previous release in the topic 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:

  • On the administrative console, click...
    Global Security > Available realm definitions > Configure > Server identity stored in repository

    Enter the user name and password and then click Apply.

  • Run a wsadmin command:
    AdminTask.configureAdminWIMUserRegistry('[-autoGenerateServerId false -serverId testuser -serverIdPassword testuserpwd -primaryAdminId testuser -ignoreCase true ]')

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

• After running the addNode.sh command, the application server 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 your truststore files.

Related:

Secure installation for client signer retrieval in SSL

Use command-line tools

Add, manage, and remove nodes

Recover or move nodes with the addNode.sh -asExistingNode command

Mapping modules to servers

Assigning users and groups to roles

Use HPEL to troubleshoot applications

addNode.sh command best practices

removeNode command

cleanupNode command