Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Application Server Enterprise Edition 8 2004Q4 Beta Administration Guide 

Chapter 3
Configuring Node Agents

This chapter describes the node agents in Application Server. It contains the following sections:

About Node Agents

Node 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. The node agent:

Automatically Created Node Agent

When you install the Application Server, a node agent is automatically created with the host name of the machine. This node agent must be manually started on the machine before it runs. Once the node agent is started, it appears in the Admin Console and when you run asadmin list-node-agents.

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 manage server instances, for example, before starting and stopping 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 before the node agent itself is physically created on the node agent's local system.

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.

Node Agent Deployment

In general, you configure and deploy your node agents in one of two ways:

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 for the latest information in the central repository. Once it successfully contacts the Domain Administration Server and gets configuration information, the node agent is bound to that Domain Administration Server.

If you created a placeholder node agent on the Domain Administration Server, when the node agent is started for the first time it gets its configuration from the Domain Administration Server's central repository.

During its initial start-up, if the node agent is unable to reach the Domain Administration Server because the Domain Administration Server 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 on the Domain Administration Server, the next time it synchronizes it stops itself and marks itself as awaiting deletion. Manually delete it using the local asadmin command delete-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. The node agent detects the synchronization failure and keeps a persistent state denoting that synchronization has failed. On next startup attempt, the node agent runs a full synchronization.

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.

Admin Console Tasks for Node Agents

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 command create-node-agent on the machine hosting the node agent to complete the creation.

  1. In the tree component, select the Node Agents node.
  2. On the Node Agents page, click New.
  3. On the Current Node Agent Placeholder page, enter a name for the new node agent.

    4. The name must be unique across all node agent names, server instance names, cluster names, and configuration names in the domain.

  4. Click OK.

    5. 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 command delete-node-agent on the node agent's local machine.

Before deleting the node agent configuration, the node agent must not be running and it must not have any associated instances.

  1. In the tree component, select the Node Agents node.
  2. On the Node Agents page, select the checkbox next to the node agent to be deleted.
  3. Click delete.

Equivalent asadmin command: delete-node-agent-config.

Editing a Node Agent Configuration

To edit a node agent configuration:

  1. In the tree component, expand the Node Agents node.
  2. Select the node agent configuration to edit.
  3. On the Node Agents General Information page, choose whether to start the agent's server instances when the agent is started. You can also manually start and stop instances from this page.

If this configuration is for a placeholder node agent, when you create the actual node agent it picks up this configuration.

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.

  1. In the tree component, expand the Node Agents node.
  2. Select the node agent configuration to edit.
  3. Click the Auth Realm tab.
  4. On the Node Agents Edit Realm page, enter a realm.

    5. 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.

  5. In the Class Name field, specify the Java class that implements the realm.
  6. Add any required properties.

    7. Authentication realms require provider-specific properties, which vary depending on what a particular implementation needs.

Editing the Node Agent's HTTP 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 HTTP listener information.

  1. In the tree component, expand the Node Agents node.
  2. Select the node agent configuration to edit.
  3. Click the JMX tab.
  4. 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.
  5. 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.
  6. In the JMX Protocol field, type the protocol that the JMX connector supports.

    7. The default is jmxmp.

  7. Click the checkbox next to Accept All Addresses to allow a connection to all IP addresses.

    8. 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.

  8. 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:

  1. Check the Enabled box in the Security field.

    2. Security is enabled by default.

  2. To have clients authenticate themselves to the server when using this listener, check the Enabled box in the Client Authentication field.
  3. Enter the name of an existing server keypair and certificate in the Certificate NickName field. See the Security chapter for more information.
  4. In the SSL3/TLS section:
    1. Check the security protocol(s) to enable on the listener. You must check either SSL3 or TLS, or both protocols.
    2. Check the cipher suite used by the protocol(s). To enable all cipher suites, check All Supported Cipher Suites.
  5. Click Save.

Tasks for Node Agents in asadmin Tool

Creating a Node Agent

To create a node agent, run the asadmin command create-node-agent locally on the machine on which the node agent runs.

For example:

$ asadmin create-node-agent --adminhost myhost --adminport 4848 ---adminuser admin nodeagent1

The default name for a node agent is the host name on which the node agent is created.

Note

In the following situations, you must specify a DNS-reachable hostname:

1. If domains cross subnet boundaries (that is, the node agent and the Domain Administration Server (DAS) are in different domains, for example, sun.com and java.com)

2. If using a DHCP machine with a host name not registered in the DNS

Specify a DNS-reachable hostname by explicitly specifying the host name for the domain and the node agent when you create them:

create-domain --domainproperties domain.hostName=DAS-host-name

create-node-agent --adminhost DAS-host-name --agentproperties remoteclientaddress=node-agent-host-name

Starting a Node Agent

Before a node agent can manage server instances, it must be running. Start a node agent by running the asadmin command start-node-agent locally on the system where the node agent resides.

For example:

$ asadmin start-node-agent --user admin nodeagent1

Stopping a Node Agent

Run the asadmin command stop-node-agent on the system where the node agent resides to stop a running node agent. The stop-node-agent command stops all server instances that the node agent manages.

For example:

$ asadmin stop-node-agent nodeagent1

Deleting a Node Agent

Run the asadmin command delete-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 and it its configuration removed using either the Admin Console or the asadmin delete-node-agent-config command.

For example:

$ asadmin delete-node-agent nodeagent1

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).



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.