Sun Java System Application Server Enterprise Edition 8.1 Administration Guide 2005Q1 |
Chapter 4
Configuring Node AgentsThis chapter describes the node agents in Application Server. It contains the following sections:
About Node AgentsNode Agents
A node agent is a lightweight agent that is required on every machine that hosts server instances, including the machine that hosts the Domain Administration Server (DAS). The node agent:
- Starts, stops, creates and deletes server instances as instructed by the Domain Administration Server.
- Restarts failed server instances.
- Provides a view of the log files of failed servers.
- Synchronizes each server instance’s local configuration repository with the Domain Administration Server’s central repository. Each local repository contains only the information pertinent to that server instance or node agent.
The following figure illustrates the overall node agent architecture:
Figure 4-1
Node Agent Architecture
Automatically Created Node Agent
When you install the Application Server, a node agent is created by default with the host name of the machine. This node agent must be manually started on the local machine before it runs.
Node Agents and Server Instance Management
You can create and delete server instances even if the node agent is not running. However, the node agent must be running before you use it to start and stop server instances.
If you stop the node agent, the server instances it manages are stopped too.
Additional Node Agents
A node agent services a single domain. If a machine hosts instances running in multiple domains, it must run multiple node agents.
Node Agent Placeholders
You can create and delete server instances without an existing node agent using a node agent placeholder. The placeholder is a node agent configuration created on the Domain Administration Server (DAS) before the node agent itself is created on the node agent’s local system.
Note
Once you’ve created a placeholder node agent, use it to create instances in the domain. However, before starting the instances you must create and start the actual node agent locally on the machine where the instances will reside using the
asadmin
command. See "Creating a Node Agent" and "Starting a Node Agent" for more information.
Deploying Node Agents
You configure and deploy your node agents in one of two ways:
Before Deploying Node Agents
Before you deploy node agents:
Once the Domain Administration Server is up and running, begin either online or offline deployment.
Online Deployment
To configure the domain if you know the topology and have the hardware for your domain before you start configuring it, use online deployment.
The following figure summarizes the online deployment of node agents:
Figure 4-2 Online Node Agent Deployment
To configure online deployment:
- Install a node agent on every machine that will host a server instance.
Use the installer or the
asadmin
commandcreate-node-agent
. If a machine requires more than one node agent, use theasadmin
commandcreate-node-agent
to create them.See "Creating a Node Agent" for more information.
- Start the node agents using the
asadmin
commandstart-node-agent
.When started, a node agent communicates with the Domain Administration Server (DAS). When it reaches the DAS, a configuration for the node agent is created on the DAS. Once the configuration exists, the node agent is viewable in the Admin Console.
See "Starting a Node Agent" for more information.
- Configure the domain, including creating server instances and clusters and deploying applications.
Offline Deployment
The offline approach lets you easily define and rearrange items in the domain before configuring the individual local machines.
The following figure summarizes the offline deployment steps.
Figure 4-3 Offline Node Agent Deployment
To configure the domain and server instances before setting up node agents on local machines (offline configuration):
- Create placeholder node agents in the Domain Administration Server.
See "Creating a Node Agent Placeholder" for more information.
- Create server instances and clusters, and deploy applications.
- Install a node agent on every machine that will host a server instance.
Use the installer or the
asadmin
commandcreate-node-agent
. The node agents must have the same names as the placeholder node agents previously created.See "Creating a Node Agent" for more information.
- Start the node agents using the
asadmin
commandstart-node-agent
.When a node agent is started, it binds to the Domain Administration Server and creates any server instances previously associated with the node agent.
See "Starting a Node Agent" for more information.
Node Agent and Domain Administration Server Synchronization
Because configuration data is stored in the Domain Administration Server’s repository (the central repository) and also cached on the node agent’s local machine, the two must be synchronized.
Node Agent Synchronization
When a node agent is started for the first time, it sends a request to the Domain Administration Server (DAS) for the latest information in the central repository. Once it successfully contacts the DAS and gets configuration information, the node agent is bound to that DAS.
If you created a placeholder node agent on the DAS, when the node agent is started for the first time it gets its configuration from the central repository of the DAS.
During its initial start-up, if the node agent is unable to reach the DAS because the DAS is not running, the node agent stops and remains unbound.
If changes are made in the domain to the node agent’s configuration, they are automatically communicated to the node agent on the local machine while the node agent is running.
If you delete a node agent configuration on the DAS, the next time the node agent synchronizes it stops itself and marks itself as awaiting deletion. Manually delete it using the local
asadmin
commanddelete-node-agent
.Server Instance Synchronization
If you explicitly start a server instance with the Admin Console or
asadmin
tool, the server instance is synchronized with the central repository. If this synchronization fails, the server instance doesn’t start.If a node agent starts a server instance without an explicit request through the Admin Console or the
asadmin
tool, the repository cache for the server instance is not synchronized. The server instance runs with the configuration as stored in its cache.Synchronizing Large Applications
When your environment contains large applications to synchronize or available memory is constrained, you can adjust the JVM options to limit memory usage. This adjustment reduces the possibility of receiving out of memory errors. The instance synchronization JVM uses default settings, but you can configure JVM options to change them.
Set the JVM options using the
INSTANCE-SYNC-JVM-OPTIONS
property. The command to set the property is:asadmin set domain.node-agent.node_agent_name.property.INSTANCE-SYNC-JVM-OPTIONS=”JVM_options"
For example:
asadmin set domain.node-agent.node0.property.INSTANCE-SYNC-JVM-OPTIONS="-Xmx32m -Xss2m"
In this example, the node agent is
node0
and the JVM options are -Xmx32m -Xss2m.For more information on JVM options, see:
http://java.sun.com/docs/hotspot/VMOptions.html
Note
Restart the node agent after changing the INSTANCE-SYNC-JVM-OPTIONS property, because the node agent is not automatically synchronized when a property is added or changed in its configuration.
Viewing Node Agent Logs
Each node agent has its own log file. If you experience problems with a node agent, see the log file at:
node_agent_dir
/
node_agent_name/agent/logs/server.log
.Sometimes the node agent log instructs you to look at a server’s log to get a detailed message about a problem.
The server logs are located at:
node_agent_dir/node_agent_name/server_name/
logs/server.log
The default location for node_agent_dir is install_dir
/nodeagents
.Tasks Available through the Admin Console and asadmin Tool
For node agents, some tasks must be performed locally on the system where the node agent runs, while others can be performed on the Domain Administration Server. Tasks that need to be performed locally are only available through the asadmin tool running on the machine where the node agent resides. Tasks that operate on the Domain Administration Server are available through the Admin Console and through the asadmin tool
The following table summarizes the tasks and where to run them:
Admin Console Tasks for Node AgentsViewing General Node Agent Information
Once a node agent or node agent placeholder has been created, to view its settings:
- In the tree component, select the Node Agents node.
- Click the name of a node agent.
If a node agent already exists but does not appear here, start the node agent on the node agent’s host machine using
asadmin start-node-agent
. See "Starting a Node Agent" for more information.- Check the node agent’s host name.
If the host name is Unknown Host, then the node agent has not made initial contact with the Domain Administration Server (DAS).
- Check the node agent status.
Running. The node agent has been properly created and is currently running.
Not Running. One of the following situations exists:
- The node agent has been created on the local machine, but has never been started.
- The node agent was started but has been stopped.
Waiting for Rendezvous. The node agent is a placeholder that has never been created on the local machine.
See "Creating a Node Agent" and "Starting a Node Agent" for more information on creating and starting node agents.
- Choose whether to start instances on start up.
Select Yes to start server instances associated with the node agent automatically when the node agent is started. Select No to start the instances manually.
- Determine whether the node agent has made contact with the Domain Administration Server.
If the node agent has never made contact with the Domain Administration Server, it has never been successfully started.
- Manage server instances associated with the node agent.
If the node agent is running, start or stop an instance by clicking the checkbox next to the instance name and clicking Start or Stop.
Creating a Node Agent Placeholder
Because the node agent must be created locally on the machine hosting the node agent, through the Admin Console you can only create a placeholder for a node agent. This placeholder is a node agent configuration for which a node agent does not yet exist.
After creating a placeholder, use the
asadmin
commandcreate-node-agent
on the machine hosting the node agent to complete the creation. For more information, see "Creating a Node Agent".
- In the tree component, select the Node Agents node.
- On the Node Agents page, click New.
- On the Current Node Agent Placeholder page, enter a name for the new node agent.
The name must be unique across all node agent names, server instance names, cluster names, and configuration names in the domain.
- Click OK.
The placeholder for your new node agent is listed on the Node Agents page.
Equivalent
asadmin
command:create-node-agent-config
.Deleting a Node Agent Configuration
Through the Admin Console you can only delete the node agent configuration from the domain. You cannot delete the actual node agent. To delete the node agent itself, run the
asadmin
commanddelete-node-agent
on the node agent’s local machine. For more information, see "Deleting a Node Agent".Before deleting the node agent configuration, the node agent must be stopped and it must not have any associated instances. To stop a node agent, use the
asadmin
commandstop-node-agent
. See "Stopping a Node Agent" for more information.Equivalent
asadmin
command:delete-node-agent-config
.Editing a Node Agent Configuration
To edit a node agent configuration:
If this configuration is for a placeholder node agent, when you create the actual node agent using
asadmin create-node-agent
, it picks up this configuration. For information on creating a node agent, see "Creating a Node Agent".If this configuration is for an existing node agent, the node agent configuration information is synchronized automatically.
Editing a Node Agent Realm
Set an authentication realm for users connecting to the node agent. Only administration users should have access to the node agent.
- In the tree component, expand the Node Agents node.
- Select the node agent configuration to edit.
- Click the Auth Realm tab.
- On the Node Agents Edit Realm page, enter a realm.
The default is
admin-realm
, created when you create the node agent. To use a different realm, replace the realms in all the components controlled by the domain or the components won’t communicate properly.- In the Class Name field, specify the Java class that implements the realm.
- Add any required properties.
Authentication realms require provider-specific properties, which vary depending on what a particular implementation needs.
Editing the Node Agent’s Listener for JMX
The node agent uses JMX to communicate with the Domain Administration Server. Therefore it must have a port to listen on for JMX requests, and other listener information.
- In the tree component, expand the Node Agents node.
- Select the node agent configuration to edit.
- Click the JMX tab.
- In the Address field, type 0.0.0.0 if the listener listens on all IP addresses for the server, using a unique port value. Otherwise, type a valid IP address for the server.
- In the Port field, type the port value for the node agent’s JMX connector to listen on. If the IP address is 0.0.0.0, the port number must be unique.
- In the JMX Protocol field, type the protocol that the JMX connector supports.
The default is rmi_jrmp.
- Click the checkbox next to Accept All Addresses to allow a connection to all IP addresses.
The node agent listens on a specific IP address associated to a network card or listens on all IP addresses. Accepting all addresses puts the value
0.0.0.0
in the “listening host address” property.- In the Realm Name field, type the name of the realm that handles authentication for the listener.
In the Security section of this page, configure the listener to use SSL, TLS, or both SSL and TLS security.
To set up a secure listener, do the following:
- Check the Enabled box in the Security field.
Security is enabled by default.
- To have clients authenticate themselves to the server when using this listener, check the Enabled box in the Client Authentication field.
- Enter the name of an existing server keypair and certificate in the Certificate NickName field. See the Security chapter for more information.
- In the SSL3/TLS section:
- Click Save.
Tasks for Node Agents in asadmin ToolCreating a Node Agent
To create a node agent, run the
asadmin
commandcreate-node-agent
locally on the machine on which the node agent runs.For example:
$ asadmin create-node-agent --host myhost --port 4849 ---user admin nodeagent1
where
myhost
is your Domain Administration Server (DAS) hostname,4849
is your DAS port number,admin
is your DAS user, andnodeagent1
is the name of the node agent you are creating.The default name for a node agent is the host name on which the node agent is created.
If you’ve already created a node agent placeholder, use the same name as the node agent placeholder to create the associated node agent. If you have not created a node agent placeholder, and the DAS is up and reachable, the
create-node-agent
command also creates a node agent configuration (placeholder) on the DAS.For a complete description of the command syntax, see the online help for the command.
Starting a Node Agent
Before a node agent can manage server instances, it must be running. Start a node agent by running the
asadmin
commandstart-node-agent
locally on the system where the node agent resides.For example:
$ asadmin start-node-agent --user admin nodeagent1
where
admin
is your admin user, andnodeagent1
is the node agent you are starting.For a complete description of the command syntax, see the online help for the command.
Stopping a Node Agent
Run the
asadmin
commandstop-node-agent
on the system where the node agent resides to stop a running node agent. Thestop-node-agent
command stops all server instances that the node agent manages.For example:
$ asadmin stop-node-agent nodeagent1
where
nodeagent1
is your node agent.For a complete description of the command syntax, see the online help for the command.
Deleting a Node Agent
Run the
asadmin
commanddelete-node-agent
on the system where the node agent resides to delete the node agent files.Before deleting a node agent, the node agent must be stopped. You can also delete a node agent if it has never been started, or never successfully able to contact the Domain Administration Server (that is, if it is still unbound).
For example:
$ asadmin delete-node-agent nodeagent1
where
nodeagent1
is your node agent.For a complete description of the command syntax, see the online help for the command.
When deleting a node agent, you must also delete its configuration from the Domain Administration Server using either the Admin Console or the
asadmin delete-node-agent-config
command