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.
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.
The following items are new in Version 6.1:
- 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, then the -startingport
option works the same as it does in Version 5.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 the addNode command. 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.
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.
newfeat Best practice: In a feature pack environment, 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
newfeatWhen a node is added to a deployment
manager that is augmented with the feature pack, the node must be
Version 6.1 or higher. If the node is lower than the Version 6.1 level,
then the addNode command fails.
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]
addNode dmgr_host [dmgr_port] [-profileName profilename]
[-conntype type] [-includeapps] [-startingport portnumber]
[-portprops qualified_filename] [-nodeagentshortname name]
[-nodegroupname name] [-includebuses 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] [-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.
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 following
directory:
profile_root/installedApps/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.
- -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.
To
avoid potential port conflicts, read about port
number settings for more information
on 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 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.
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.
addNode mydmgr 11383 -profileName mynode (adds profile, mynode, to the Network
Deployment cell managed by profile mydmgr, which listens on SOAP port 11383)
Security considerations when adding an application
server node to Network Deployment cell
When
adding a node to the cell, you automatically inherit both the user
registry and the authentication mechanism of the 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 ), 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:
- 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, respectively. 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 on the addNode syntax.
You can
also run the addNode command using the z/OS Customization dialog.
If you issue the addNode command with security enabled using the z/OS
Customization dialog or command prompt, you must use a user ID with
authority and specify the -user and -password options.
- 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 communicate with the keystore files and System Authorization
Facility (SAF) keyring that is owned by the deployment manager and
vice versa. If you generate certificates for the deployment manager
using the same certificate authority as you used for the node agent
process, then you are successful. The following SSL configurations
must contain keystores and truststores that can interoperate:
- System SSL repertoire that is 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 that is specified in NodeAgent System Administration
> Node agents > NodeAgent Server > Administration Services > JMX Connectors
> SOAPConnector > Custom properties > sslConfig
WebSphere Application Server for z/OS defines
security domain names using the z/OS Customization Dialog. Use caution
when adding a node to a Deployment Manager configuration that defines
a different security domain.
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.
- When a client from a previous release tries to
use the addNode command to federate to a Version 6.1 deployment manager,
the client must first obtain signers for a successful handshake. For
more information, read about obtaining signers from a previous release
in the article on Secure installation for client retrieval.
- 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.