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.
Your user profile must have *ALLOBJ authority
or must have read and execute authority for the addNode Qshell script.
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.
When you run the addNode command, the command
stops the running application server that it is incorporating into
a cell. You can optionally stop the application server before running
the addNode command.
When you add a node, the product might generate ports. The following
items apply to port generation:
- Ports generated for the node agent are unique for all the profiles
in the installation. For development purposes, you can create multiple
profiles on the same installation and add them to one or more cells
without concern for port conflicts.
- If you want to specify the ports that the node agent uses, 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
the serverindex.xml file.
- If you want to use a number of sequential ports, consider the
-startingport option. This means that port conflicts with other profiles
are not detected.
Best practice: Use the -includeapps option for the
addNode command
to ensure that the environment starts with the same version of the
application. If any custom policy set is created on the server before
you run the
addNode command, then the custom policy
set is not copied to the new cell after you run the
addNode command.
Therefore, when using the -installApps option, an application on the
server that uses the custom policy set fails to load the policy set
after you run the
addNode command. You can export
the custom policy set from the stand-alone server before you run the
addNode command,
and import the custom policy set to the new cell after you run the
addNode command.
bprac
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] [-conntype type] [-includeapps] [-includebuses name]
[-startingport portnumber] [-portprops qualified_filename]
[-nodeagentshortname name] [-nodegroupname name] [-registerservice]
[-serviceusername name] [-servicepassword password] [-coregroupname name]
[-noagent] [-statusport port] [-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 Java Management
Extensions (JMX) connector type for the command. If you 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.
New feature: This topic
references one or more of the application server log files. Beginning
in WebSphere Application Server Version 8.0 you can configure the
server to use the High Performance Extensible Logging (HPEL) log and
trace infrastructure instead of using
SystemOut.log ,
SystemErr.log,
trace.log,
and
activity.log files or native z/OS logging
facilities. If you are using HPEL, you can access all of your log
and trace information using the LogViewer command-line tool from your
server profile bin directory. See the information about using HPEL
to troubleshoot applications for more information on using HPEL.
newfeat
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. SOAP is the default Java Management
Extensions (JMX) connector type for the command. Other valid types
are JSR160RMI 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 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 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
binary files are extracted in the profile_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, profile_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 command runs, the binary
files are moved to the
profile_root/installedApps/currentCellName directory.
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.
- -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
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.
- -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 before
federation, or by modifying the ports in the node agent section of
the serverindex.xml file.
- -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.
-
- 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.
- -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 the addNode 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 command
prints in normal mode.
- -nowait
- Tells the addNode command not to wait for successful
initialization of the launched node agent process.
- -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.
- -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.
- -trace
- Generates additional trace information in the log file for debugging
purposes.
- -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.
- -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.
- -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.
- -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.
- -excludesecuritydomains true | false
- Set the -excludesecuritydomains parameter to true if you 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
you 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
- Specifies to recover an existing managed node of a deployment
manager cell.
Use the -asExistingNode parameter of the
addNode 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, you can use the
addNode -asExistingNode
option to recreate the unavailable node by completing the following
steps:
- Create a new profile with the same node and profile name as the
unavailable node. You can create the profile on a different machine
from the original node.
- For the new profile, run the addNode command
with the -asExistingNode option.
You can also use the -asExistingNode option of the addNode 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 -asExistingNode command.
Avoid trouble: 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,
or -excludesecuritydomains.
gotcha
- -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.
addNode mydmgr 11383 -profileName mynode (adds profile, mynode, to the cell managed by profile mydmgr, which listens on SOAP port 11383)
Security considerations when adding an application
server node to WebSphere Application Server, Network Deployment 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, 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. Before
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:
- When attempting to run system management commands such as the addNode command,
specify administrative credentials to perform the operation. The addNode command
accepts -username and -password parameters to specify the user ID
and password. The user ID and password that are 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 command:
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 deployment manager are not the same. To correct this failure,
either make the user registries the same or turn off security. If
you change the user registries, remember to verify that the users-to-roles
and groups-to-roles mappings are correct. Read about the addNode command
for more information about the addNode syntax.
- Adding a secured remote node through the administrative console
is not supported. You can either disable security on the remote node
before performing the operation or perform the operation from the
command prompt using the addNode script.
- Before running the addNode command,
you must verify that the truststore files on the nodes can communicate
with the keystore files from the deployment manager 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 Version 7 or 8 deployment manager,
the deployment manager cannot use the auto-generated internal server
ID to federate a Version 6.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 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 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:
The server must be restarted for these changes to take effect.
- After running the addNode 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.