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