Monitoring the Sun ONE Application Server

This module contains information about the monitoring and Simple Network Management Protocol (SNMP) features and functions available in the Sun ONE Application Server.

This module includes the following sections:

• About Monitoring the Sun ONE Application Server
• Extracting Monitoring Data Using the CLI
• Administering the Transaction Service Using the CLI
• Using HTTP Quality of Service
• About SNMP
• Setting Up SNMP
• Enabling and Starting the SNMP Master Agent

About Monitoring the Sun ONE Application Server

---

You can monitor the Sun ONE Application Server by collecting activity statistics from strategic data points on your system. The statistics show you how many requests your server is handling and how well it is handling those requests. You can view some statistics for individual virtual servers and others for the entire application server instance. Either the asadmin utility or SNMP can be used to monitor the Sun ONE Application Server.

The following topics are addressed in this section:

• Statistics
• SNMP
• HTTP Server Monitoring
• Application Components and Subsystems Monitoring
• Quality of Service (QOS)

Statistics

Statistics collection is always enabled for most of the Sun ONE Application Server application components and subsystems, including the HTTP server; no enabling functions are required. However, there are some statistics that are collected only when monitoring is explicitly enabled on that subsystem, or only when relevant functionality is enabled. These statistics include the following data points:

• Statistics for EJB methods
• Active transactions
• Connections (only if Quality of Service is enabled)
• DNS (only if DNS Cache is enabled)

Monitoring can be enabled for application subsystems or components from the Administration interface, as described in "Application Components and Subsystems Monitoring".

If the server monitor reports that the server is handling a large number of requests, you may need to adjust the server configuration or the system's network kernel. For more information on adjusting your server's configuration, see the Sun ONE Application Server Performance Tuning and Sizing Guide.

SNMP

The Sun ONE Application Server provides network management information through its information gathering tools using Simple Network Management Protocol (SNMP), a protocol used to exchange management and monitoring information across a network. Using SNMP, programs called agents monitor various devices on the network (hubs, routers, bridges, and so on). Another program collects the data from the agents. The database created by the monitoring operations is called a management information base (MIB).This data is used to check if all devices on the network are operating properly.

While only the HTTP server can be monitored using SNMP; all components and systems can be monitored using the command-line interface (CLI)

For more information on SNMP, see "About SNMP" and "Setting Up SNMP".

HTTP Server Monitoring

HTTP server monitoring is enabled by default, which means it doesn't need to be specifically turned on. HTTP server monitoring is based on an XML file and is accessed using the asadmin command as a set of three monitorable attributes. The elements, subelements, and the attributes of this XML file are described in "Monitorable HTTP Server Elements" and "Monitorable HTTP Server Attributes".

---

Note	Only HTTP server statistics are available using SNMP. Statistics for all the subsystems of the Sun ONE Application Server, including the HTTP server, are available using the command-line interface.

---

For more information about using asadmin, see "Using the Command Line Interface".

Application Components and Subsystems Monitoring

Some of the subsystems or components within the Sun ONE Application Server do not need to have monitoring enabled because the relevant statistics are always collected. For example, monitoring for application components such as containers can be enabled or disabled. When monitoring is enabled, in addition to the statistics that are always collected, additional statistics on all EJB methods are also collected. Monitoring for JDBC connection pools is always enabled. A connection pool is initialized upon first access and relevant statistics can be monitored anytime after that.

For a full list of monitorable data points, see "Monitorable Attribute Names".

You can enable monitoring for selected application components and subsystems from the Administration interface or from the command-line interface (CLI). For example, to enable monitoring from the CLI for the EJB container, type the following command from a terminal window:

set server1.ejb-container.monitoringEnabled=true
reconfig server1

where server1 is the instance name.

The equivalent functionality can be accessed on the Administration interface under the Containers node.

The following topics are addressed in this section:

• Monitoring for Container Subsystems
• Monitoring for the ORB Service
• Monitoring for the Transaction Service

Monitoring for Container Subsystems

In the case of the EJB container, when monitoring is enabled, the statistics related to the methods for all entity beans, stateful session beans, and stateless session beans are collected. These statistics include:

• Total number of errors
• Total number of calls
• Total number of successes
• Execution time, in milliseconds (for last invocation of the method)

All other statistics for container subsystems are always collected. Some of the monitored data points include statistics relative to:

• Initial, minimum, and maximum stateless beans in pool
• Minimum and preferred number of stateful and entity beans in cache
• Minimum and preferred number of stateless session beans in cache
• Number of beans created and destroyed
• Other related statistics

Monitoring for the ORB Service

For the ORB service, monitored data points include statistics gathered for the ORB connection and the ORB thread pool. ORB statistics are always collected and, therefore, it is not necessary to enable monitoring for the ORB service.

Monitoring for the Transaction Service

For the Java Transaction Service (JTS) service, monitored data points include:

• Total completed transactions
• Total rolled back transactions
• Total inflight transactions
• List of inflight transactions

Refer to "Administering the Transaction Service Using the CLI" for further information.

Quality of Service (QOS)

Quality of Service refers to the performance limits you set for a server instance virtual server class or virtual server. For example, if you are an Internet Service Provider (ISP), you might want to charge different fees for virtual servers depending on how much bandwidth is provided. You can limit two areas: the amount of bandwidth and the number of connections.

The Quality of Service information provided by the Sun ONE Application Server is used to determine server efficiency during runtime with respect to:

• Start-up time
• Server traffic and effects of traffic upon bandwidth
• Analysis of live versus static data
• Other data elements

For more information, see "Administering the Transaction Service Using the CLI".

Extracting Monitoring Data Using the CLI

---

With the asadmin command, you can extract monitored data through the command-line interface (CLI) using the list and get commands.

---

Note	The set command is only used to set monitoring for the transaction service as described in "Administering the Transaction Service Using the CLI".

---

This section addresses the following topics:

• The list --monitor Command
• The get --monitor Command
• CLI Name Mapping
• HTTP Server Monitorable Objects

The list --monitor Command

The list command provides information about the application components and subsystems currently being monitored for the specified server instance name. Using this command, you can see the monitorable components and sub-components for a server instance.

Example

asadmin> list --monitor server1

returns the following list of application components and subsystems that have monitoring enabled:

iiop-service
transaction-service
application.converter
application.myApp
http-server

You can also list applications that are currently monitored in the specified server instance. This can be useful when particular monitoring statistics are sought from an application using the get command.

Example

asadmin> list --monitor server1.application

returns:

converter
myApp

For a more comprehensive example, see "Petstore Example".

The get --monitor Command

This command retrieves the following monitored information:

• All attribute(s) monitored within a component or subsystem
• Specific attribute monitored within a component or subsystem

When an attribute is requested that does not exist for a particular component or subsystem, an error is returned. Similarly, when a specific attribute is requested that is not active for a component or subsystem, an error is returned.

Refer to "CLI Name Mapping" for more information on the use of the get command.

Example 1

Attempt to get all attributes from a subsystem for a specific attribute:

asadmin> get --monitor server1.iiop-service.orb.system.orb-connection.*

total-inbound-connections=1
total-outbound-connections=1

Example 2

Attempt to get all attributes from a J2EE application:

asadmin> get --monitor server1.application.converter.*

Attribute name(s) not found

There are no monitorable attributes exposed at the J2EE-application level, therefore the command fails.

Example 3

Attempt to get a specific attribute from a subsystem:

asadmin> get --monitor server1.transaction-service.inflight-tx

Attribute name = inflight-tx Value = No active transaction found.

Example 4

Attempt to get an unknown attribute from within a subsystem attribute:

asadmin> get --monitor server1.iiop-service.orb.system.orb-connection.bad-name

Could not get the attribute

Execution failed for the command: get --monitor server1.iiop-service.orb-connection.bad-name

CLI Name Mapping

The Sun ONE Application Server uses a tree structure to track monitorable objects. Every node in the tree has a name and a type. If a type is singleton, only a single node of the type can exist under any parent node. For more information on type of nodes in this tree, see "Monitorable Object Types".

The root object in the tree is represented by the Sun ONE Application Server instance name. For example, the root monitoring object for an instance named server1 is:

server1

All child objects are then addressed using the dot (.) character as separator. If a child node is of singleton type, then only the monitoring object type is needed to address the object, otherwise a name of the form type.name is needed to address the object.

For example, http-server is one of the valid monitorable object types and is singleton. To address a singleton child node representing the http-server of instance server1, the name is:

server1.http-server

Another example, application, is a valid monitorable object type and is not a singleton. To address a non-singleton child node representing the application Petstore, the name is:

server1.application.petstore

The CLI names can also address specific attributes in monitorable objects. For example, http-server has a monitorable attribute called summary. The following name addresses the summary attribute:

server1.http-server.summary

There is no fixed naming convention for attribute names exposed by monitoring objects.

You are not expected to know the valid names for CLI use. The list command lets you inspect available monitorable objects, while the get command used with a wildcard parameter allows you to inspect all available attributes on any monitorable object.

The following example illustrate some client name mapping scenarios:

Petstore Example

A user wants to inspect the number of calls made to a method in the Petstore application deployed on the Sun ONE Application Server instance named server1. A combination of the list and get commands is used to access desired statistics on a method.

1. Invoke the CLI in multi-mode.
2. Set some useful environment variables to avoid entering them for every command:

asadmin>export AS_ADMIN_USER=admin AS_ADMIN_PASSWORD=admin123

asadmin>export AS_ADMIN_HOST=localhost AS_ADMIN_PORT=4848

3. List monitorable components for instance server1:

asadmin>list --monitor server1

Output is:
iiop-service
transaction-service
application.CometEJB
application.ConverterApp
application.petstore
http-server
resources

The list of monitorable components includes iiop-service, http-server, transaction-service, resources, and all deployed (and enabled) applications.

4. List the monitorable subcomponents in the Petstore application (-m can be used instead of --monitor):

asadmin>list -m server1.application.petstore

Output is:
ejb-module.signon-ejb_jar
ejb-module.catalog-ejb_jar
ejb-module.uidgen-ejb_jar
ejb-module.customer-ejb_jar
ejb-module.petstore-ejb_jar
ejb-module.AsyncSenderJAR_jar
ejb-module.cart-ejb_jar

5. List the monitorable subcomponents in the EJB module sigon-ejb_jar of the Petstore application:

asadmin>list -m server1.application.petstore.ejb-module.signon-ejb_jar

Output is:
entity-bean.UserEJB
stateless-session-bean.SignOnEJB

6. List the monitorable subcomponents in the entity bean UserEJB for the EJB module sigon-ejb_jar of the Petstore application:

asadmin>list -m server1.application.petstore.ejb-module.signon-ejb_jar.entity-bean.UserEJB

Output is:
bean-method.create0
bean-method.findByPrimaryKey1
bean-method.remove2
bean-method.getUserName3
bean-method.setPassword4
bean-method.getPassword5
bean-method.matchPassword6
bean-method.remove7
bean-method.isIdentical8
bean-method.getEJBLocalHome9
bean-method.getPrimaryKey10
bean-pool
bean-cache

7. List the monitorable subcomponents in the method getUserName3 for the entity bean UserEJB in the EJB module sigon-ejb_jar of the Petstore application:

asadmin>list -m server1.application.petstore.ejb-module.signon-ejb_jar.entity-bean.UserEJB.bean-m ethod.getUserName3

Output is:

No monitorable entities for element
server1.application.petstore.ejb-module.signon-ejb_jar.entity-bean.UserEJB.bean-m ethod.getUserName3

8. There are no monitorable subcomponents for methods. Get all monitorable statistics for the method getUserName3.

asadmin>get -m server1.application.petstore.ejb-module. signon-ejb_jar.entity-bean.UserEJB.bean-method.getUserName3.*
method-name = public abstract java.lang.String com.sun.j2ee.blueprints.signon.user.ejb.UserLocal.getUserName()
total-num-errors = 0
total-num-success = 2
execution-time-millis = 1
total-num-calls = 2

9. You can also get a specific statistic, such as execution time.

asadmin>get -m server1.application.petstore.ejb-module. signon-ejb_jar.entity-bean.UserEJB.bean-method.getUserName3.execution-time-millis
execution-time-millis = 1

Monitorable Object Types

The tree of objects used for monitoring contains several nodes. A node is a specific entry in the object tree, and is identified uniquely by its type, name, and parent node. Some of the node types are singleton, meaning that only one node of the type can exist under a parent node. A name is not relevant for a singleton node.

A non-singleton type node needs a name. The Instance Name column describes the possible namespace.

The following table describes the tree structure in terms of possible parent-child relationships among various node types and the namespaces for some of the node types.

   Monitoring Object Types 

Node Type	Single- ton?	Leaf?	Child Node Types	Instance Names
root	Yes	No	http-server iiop-service resources transaction-service application standalone-ejb-module
http-server	Yes	No	virtual-server process
virtual-server	Yes	Yes
process	Yes	Yes
iiop-service	Yes	Yes	orb
orb	No	No	orb-connection orb-thread-pool	system is reserved for system ORB. All user ORBs get a name derived from TCP endpoint.
orb-connection	Yes	Yes
orb-thread-pool	Yes	Yes
resources	Yes	No	jdbc-connection-pool
jdbc-connection-pool	No	Yes		The names are the same as those specified by the user while creating a connection pool.
transaction-service	Yes	Yes
application	No	No	ejb-module	Name of the application as registered in server.xml.
ejb-module	No	No	stateless-session-bean stateful-session-bean entity-bean message-driven-bean	Name of the EJB module. It is derived from the EJB JAR name.
standalone-ejb-module	No	No	stateless-session-bean stateful-session-bean entity-bean message-driven-bean	Name of the standalone EJB module as registered in server.xml.
stateless-session-bean	No	No	bean-pool bean-method	Name of the bean from the deployment descriptor.
stateful-session-bean	No	No	bean-cache bean-method	Name of the bean from the deployment descriptor.
entity-bean	No	No	bean-cache bean-pool bean-method	Name of the bean from the deployment descriptor.
message-driven-bean	No	No	bean-pool bean-method	Name of the bean from the deployment descriptor.
bean-pool	Yes	Yes
bean-cache	Yes	Yes
bean-method	No	Yes		onMessage for message-driven beans, method name followed by a numeric suffix for methods in other enterprise beans. (The suffix is needed to disambiguate overloaded methods.)

Monitorable Attribute Names

It is not necessary for every monitorable object to expose monitorable attributes. Some of the objects are used just for grouping other objects. For the Sun ONE Application Server, except for an http-server node, only the leaf nodes of the tree have attributes. The http-server node type has attributes as well as child nodes. The following tables list possible monitorable attribute names for various nodes.

   http-server

Attribute Name	Datatype	Description
summary	String (Formatted)	HTTP server summary. Includes virtual servers and processes. NOTE: See section "HTTP Server Monitorable Objects" for more information on what data is exposed in the formatted string.

   virtual-server

Attribute Name	Datatype	Description
<vs-id>	String (Formatted)	Virtual server information. For every application server instance there can be one or more virtual servers. The list of virtual server IDs can be obtained from the summary attribute of http-server. You can look up statistics for a specific virtual server using the get command parameter of the form server1.http-server.virtual-server.<vs-id>. You can look up statistics for all virtual servers using the get command parameter of the form server1.http-server.virtual-server.*. NOTE: See section "HTTP Server Monitorable Objects" for more information on what data is exposed in the formatted string.

   process

Attribute Name	Datatype	Description
<pid>	String (Formatted)	Process information. For every application server instance there is one process. The process ID can be obtained from the summary attribute of http-server. Statistics for a process can be obtained using the parameter of the form server1.http-server.process.<pid> to the get command. NOTE: See section "HTTP Server Monitorable Objects" for more information on what data is exposed in the formatted string.

   orb-connection 

Attribute Name	Datatype	Description
total-inbound-connections	Integer	Total inbound connections to ORB.
total-outbound-connections	Integer	Total outbound connections from ORB.

   orb-thread-pool  

Attribute Name	Datatype	Description
thread-pool-size	Integer	Total number of threads in ORB thread pool.
waiting-thread-count	Integer	Number of thread pool threads waiting for work to arrive.

   jdbc-connection-pool 

Attribute Name	Datatype	Description
total-threads-waiting	Integer	Total threads waiting for JDBC connection.
total-outbound-connections	Integer	Total JDBC connection validation failures.
total-connections-timed-out	Integer	Total connection requests timed out.

   transaction-service 

Attribute Name	Datatype	Description
total-tx-completed	Integer	Total completed transactions.
total-tx-rolled-back	Integer	Total rolled back transactions.
total-tx-inflight	Integer	Total inflight (live) transactions.
isFrozen	String	Is transaction system frozen (true or false)?
inflight-tx	String (Formatted)	List of inflight transactions.

   bean-pool 

Attribute Name	Datatype	Description
max-pool-size	Integer	The maximum number of bean instances in the pool.
steady-pool-size	Integer	The number of bean instances normally maintained in the pool. When a pool is first created, it will be populated with a size equal to steady-pool-size. When an instance is removed from the pool, it is replenished asynchronously, so that the pool size is at, or above, steady-pool-size.
pool-resize-quantity	Integer	The increment by which pool grows up to max-pool-size or shrinks to steady-pool-size
idle-timeout-in-seconds	Integer	Defines the rate at which the pool cleaning thread is executed. Checks if the current size is greater than the steady pool size and removes pool-resize-quantity elements. If the current size is less than steady-pool-size, it is increased by pool-resize-quantity, with a ceiling of min (current-pool-size+pool + resize-quantity, max-pool-size). Only objects that have not been accessed for more than pool-idle-timeout-in-seconds are candidates for removal
num-beans-in-pool	Integer	Number of beans available in pool.
num-threads-waiting	Integer	Number of threads waiting for free beans.
total-beans-created	Integer	Number of beans created so far.
total-beans-destroyed	Integer	Number of beans destroyed so far.
jms-max-messages-load	Integer	The maximum number of messages to load into a JMS session at one time for a message-driven bean to serve. Default is 1. Applies only to pools for message driven beans.

   bean-cache 

Attribute Name	Datatype	Description
cache-resize-quantity (resize-quantity)	Integer	The quantity by which the cache size is reduced when the number of beans in cache equals max-cache-size (that is, when cache overflow occurs.)
cache-misses	Integer	The number of times a user request did not find a bean in the cache.
idle-timeout-in-seconds	Integer	Rate at which the cache cleaner thread is scheduled. This cleaner thread examines all beans in the cache and passivates those beans that are not accessed for cache-idle-timeout-in-seconds.
cache-hits	Integer	The number of times a user request found an entry in the cache.
total-beans-in-cache	Integer	The number of beans in the cache. This is the current size of the cache.
max-beans-in-cache	Integer	Maximum number of beans that can be held in the cache beyond which cache overflow occurs.
num-passivations	Integer	Number of passivations. Applies only to stateful session beans.
num-passivation-errors	Integer	Number of errors during passivation. Applies only to stateful session beans.
num-expired-sessions-removed	Integer	Number of expired sessions removed by the cleanup thread. Applies only to stateful session beans.
num-passivation-success	Integer	Number of times passivation completed successfully. Applies only to stateful session beans.

   bean-method 

Attribute Name	Datatype	Description
method-name	String	Fully qualified name of the method.
total-num-calls	Integer	Number of times the method has been invoked. This is collected for stateless and stateful session beans and entity beans if monitoring enabled is true for EJB container, and for message-driven beans if monitoring is enabled for the message-driven bean container.
total-num-errors	Integer	Number of times the method execution resulted in an exception. This is collected for stateless and stateful session beans and entity beans if monitoring is enabled under EJB settings, and for message-driven beans if monitoring is enabled under MDB settings.
total-num-success	Integer	Number of times the method successfully executed. This is collected for stateless and stateful session beans and entity beans if monitoring enabled is true for EJB container, and for message-driven beans if monitoring is enabled for the container.
execution-time-millis	Long	Time spent executing the method for the last successful run of this method. This is collected for stateless and stateful session beans and entity beans if monitoring is enabled on the EJB container and for message-driven beans if monitoring is enabled on the container.

HTTP Server Monitorable Objects

The HTTP server monitorable attribute name summary prints the attribute values of the Server element and a summary of its subelements, including the number of each subelement and attribute values for each subelement. The HTTP server virtual-server attribute prints the attribute values of the VirtualServer element and the details of each of its subelements.The process attribute prints the attribute values of the Process element and the details of each of its subelements.

To enable NSAPI performance profiling and obtain statistics on the Profile and ProfileBucket elements, see the Sun ONE Application Server Developer's Guide to NSAPI.

For information on how to use the monitoring statistics for performance tuning, see the Sun ONE Application Server Performance and Tuning Guide.

Monitorable HTTP Server Elements

The following table lists the HTTP server monitorable elements.

   Monitorable HTTP Server Elements 

Element Name	Subelements	Description
Server	ConnectionQueue ThreadPool Profile Process VirtualServer	A server instance.
ConnectionQueue	None	The queue in which requests are held prior to being serviced. There is only one connection queue in Sun ONE Application Server 7.
ThreadPool	None	A thread pool, as defined in the init.conf file.
Profile	None	An NSAPI performance profile bucket, as defined in the init.conf file.
Process	ConnectionQueueBucketThreadPoolBucket DnsBucket DnsBucket KeepaliveBucket CacheBucket Thread	A single server process within a server instance.
ConnectionQueueBucket	None	Tracks statistics pertaining to a specific ConnectionQueue.
ThreadPoolBucket	ThreadPoolBucket	Tracks statistics pertaining to a specific ThreadPool.
DnsBucket	None	Tracks DNS statistics.
KeepaliveBucket	None	Tracks keepalive (persistent connection) statistics.
CacheBucket	None	Tracks file cache (NSFC) statistics.
Thread	RequestBucket ProfileBucket	Describes a request processing thread.
VirtualServer	RequestBucket ProfileBucket	Describes a virtual server.
RequestBucket	None	Tracks request-related statistics.
ProfileBucket		Tracks statistics pertaining to a Profile element.

Monitorable HTTP Server Attributes

The following tables list the HTTP server monitorable attributes.

   Server 

Attribute Name	Values	Description
Id		The server instance ID (for example, server1).
VersionServer		A string that contains the Sun ONE Application Server version.
TimeStarted	GMT	The time this server instance was started.
SecondsRunning		The number of seconds since this server instance started.
TicksPerSecond		The number of ticks in a second. This value is system-dependent.
MaxProcs		The maximum number of processes.
MaxThreads		The maximum number of processing threads.
MaxVirtualServers		The maximum number of virtual servers tracked.
FlagProfilingEnabled	0 (off), 1 (on)	Indicates whether NSAPI performance profiling is enabled (on).
FlagVirtualServerOverflow	0 (no), 1 (yes)	Indicates whether more than MaxVirtualServers are configured (yes). If this attribute is set to 1, statistics are not being tracked for all virtual servers.
LoadMinuteAverage		Average load in 1 minute.
Load5MinuteAverage		Average load in 5 minutes.
Load15MinuteAverage		Average load in 15 minutes.
RateBytesTransmitted	bytes per second	The rate at which data is transmitted over some server-defined interval, or 0 if this information is not available.
RateBytesReceived	bytes per second	The rate at which data is received over some server-defined interval, or 0 if this information is not available.

   ConnectionQueue 

Attribute Name	Values	Description
Id		The connection queue ID.

   ThreadPool 

Attribute Name	Values	Description
Id		The thread pool ID.
Name		The symbolic name of the thread pool.

   Profile 

Attribute Name	Values	Description
Id		The NSAPI performance profile bucket ID.
Name		The symbolic name of the NSAPI performance profile bucket.
Description		The description of the NSAPI performance profile bucket.

   Process 

Attribute Name	Values	Description
Pid		The operating system process identifier that uniquely identifies this process.
Mode	unknown active	Displays active when this process is active.
TimeStarted	GMT	The time this process was started.
CountConfigurations		The number of times a configuration has been loaded, or 0 if this information is not available.
SizeVirtual	kilobytes	The size of virtual memory used by this process.
SizeResident	kilobytes	The size of the resident memory used by this process.
FractionSystemMemoryUsage		Fraction of system memory used by this process.

   ConnectionQueueBucket 

Attribute Name	Values	Description
ConnectionQueue		The ID of a ConnectionQueue element.
CountTotalConnection		The total number of new connections that have been accepted.
CountQueued		The number of connections currently enqueued.
PeakQueued		The largest number of connections that have been in the queue simultaneously.
MaxQueued		The maximum number of connections that can be in the queue.
CountOverflow		The number of times the queue has been too full to accommodate a connection.
CountTotalQueued		The total number of connections that have been queued. A given connection may be queued multiple times, so CountTotalQueued may be greater than or equal to CountTotalConnections.
TicksTotalQueued		The total number of ticks that connections have spent in the queue. A tick is a system-dependent unit of time; see TicksPerSecond.

   ThreadPoolBucket 

Attribute Name	Values	Description
Thread-pool		The ID of a ThreadPool element.
CountThreadsIdle		The number of request processing threads currently idle.
CountThreads		The number of request processing threads.
MaxThreads		The maximum number of request processing threads that can exist concurrently.
CountQueued		The number of requests queued for processing by this thread pool.
PeakQueued		The largest number of requests that have been in the queue simultaneously.
MaxQueued		The maximum number of requests that can be in the queue.

   DnsBucket 

Attribute Name	Values	Description
FlagCacheEnabled	0 (off), 1 (on)	Indicates whether the DNS cache is enabled (on).
CountCacheEntries		The number of DNS entries presently in the cache.
MaxCacheEntries		The maximum number of DNS entries the cache can accommodate.
CountCacheHits		The number of times a DNS cache lookup has succeeded.
CountCacheMisses		The number of times a DNS cache lookup has failed.
FlagAsyncEnabled	0 (off), 1 (on)	Indicates whether asynchronous DNS lookups are enabled (on).
CountAsyncNameLookups		The total number of asynchronous DNS name lookups performed.
CountAsyncAddrLookups		The total number of asynchronous DNS address lookups performed.
CountAsyncLookupsInProgress		The total number of asynchronous DNS lookups currently in progress.

   KeepaliveBucket 

Attribute Name	Values	Description
CountConnections		The number of connections currently in keepalive mode.
MaxConnections		The maximum number of simultaneous keepalive connections.
CountHits		The total number of times connections in keepalive mode have subsequently made a valid request.
CountFlushes		The number of times keepalive connections have been closed by the server.
CountTimeouts		The number of times keepalive connections have timed out.
SecondsTimeouts		The number of seconds before the server closes an idle keepalive connection.
CountRefusals		The number of times keepalive connections have been refused by the server.

   CacheBucket 

Attribute Name	Values	Description
FlagEnabled	0 (off), 1 (on)	Indicates whether the file cache is enabled (on).
SecondsMaxAge	Number of seconds	The maximum age of a file cache entry.
CountEntries		The number of entries currently in the file cache.
MaxEntries		The maximum number of cache entries the file cache can accommodate simultaneously.
CountOpenEntries		The number of entries associated with an open file.
MaxOpenEntries		The maximum number of cache entries associated with an open file that the file cache can accommodate simultaneously.
SizeHeapCache	Number of bytes	The amount of heap used by cached file content.
MaxHeapCacheSize	Number of bytes	The maximum amount of heap the file cache uses for cached file content.
SizeMmapCache	Number of bytes	The amount of address space used by memory mapped file content.
MaxMmapCacheSize	Number of bytes	The maximum amount of address space that the file cache uses for memory mapped file content.
CountHits		The number of times a cache entry lookup has succeeded.
CountMisses		The number of times a cache entry lookup has failed.
CountInfoHits		The number of times a file information lookup has succeeded.
CountInfoMisses		The number of times a file information lookup has failed.
CountContentHits		The number of times a content lookup has succeeded.
CountContentMisses		The number of times a content lookup has failed.

   Thread 

Attribute Name	Values	Description
Mode	unknown, idle, DNS, request, processing, response, updating	The thread's last known status.
TimeStarted	GMT	The time this thread was started.
ConnectionQueue		The ID of the ConnectionQueue the thread is servicing.

   VirtualServer 

Attribute Name	Values	Description
Id		The virtual server ID.
Mode	unknown, active	Displays active when this virtual server is active.
Hosts		The software virtual server hostnames serviced by this virtual server (for example, www.foo.com foo.com foo.isp.com).
Interfaces		The interfaces (listeners) the virtual server is configured for (for example, 192.168.1.2:80 192.168.1.2:443).

   RequestBucket 

Attribute Name	Values	Description
CountRequests		The number of requests serviced.
CountBytesReceived		The number of bytes received, or 0 if this information is not available.
CountBytesTransmitted		The number of bytes transmitted, or 0 if this information is not available.
RateBytesTransmitted	bytes per second	The rate at which data was transmitted over some server-defined interval, or 0 if this information is not available.
MaxByteTransmissionRate		The maximum rate at which data was transmitted over some server-defined interval, or 0 if this information is not available.
CountOpenConnections		The number of open connections, or 0 if this information is not available.
MaxOpenConnections		The maximum number of open connections, or 0 if this information is not available.
Count2xx		The number of 200-level responses sent.
Count3xx		The number of 300-level responses sent.
Count4xx		The number of 400-level responses sent.
Count5xx		The number of 500-level responses sent.
CountOther		The number of responses sent that were not 200, 300, 400, or 500 level.
Count200		The number of 200-level responses sent.
Count302		The number of 302-level responses sent.
Count304		The number of 304-level responses sent.
Count400		The number of 400-level responses sent.
Count401		The number of 401-level responses sent.
Count403		The number of 403-level responses sent.
Count404		The number of 404-level responses sent.
Count503		The number of 503-level responses sent.

   ProfileBucket 

Attribute Name	Values	Description
Profile		The ID of a Profile element.
Countcalls		The number of calls to NSAPI SAFs.
CountRequests		The number of requests processed.
TicksDispatch		The number of ticks spent dispatching requests. A tick is a system-dependent unit of time; see TicksPerSecond.
TicksFunction		The number of ticks spent in NSAPI SAFs. A tick is a system-dependent unit of time; see TicksPerSecond.

Administering the Transaction Service Using the CLI

---

You can use the set command to administer the statistics you want to monitor for the JTS.

Example 1

To add a transaction to a rollback list (which results in rollback or specified transaction), issue the set command as follows:

set --monitor server1.transaction-service.rollback-list=txnid1

Example 2

To freeze the transaction service, issue the set command as follows:

set --monitor server1.transaction-service.freeze=true

The following table describes the attributes that can be monitored to gather statistics for the JTS. These attributes can be set from the command line according to the rules described in "CLI Name Mapping".

For more information on the java transaction service, refer to "Using Transaction Services."

Using HTTP Quality of Service

---

The following settings govern how traffic is counted and how often the bandwidth is recomputed:

• Recompute interval—Indicates how often (in milliseconds) the bandwidth is computed.
• Metric interval—The period of time for which data is used in traffic calculations.

In the Administration interface, you can enable these server or class-level settings for the server instance or for a class of virtual servers. However, you can override them for an individual virtual server.

This section includes the following topics:

• Quality of Service Example
• Configuring Quality of Service (QOS)
• Required Changes to the obj.conf File
• Known Limitations to Quality of Service

Quality of Service Example

The following example shows how the Quality of Service information is collected and computed.

• The server has metric interval of 30 seconds.
• The server starts up at a time of 0 seconds.
• At 1 second, an HTTP connection generates 5000 bytes of traffic to/from the server.
• No more connections are made after that. At 30 seconds, the total traffic for the last 30 seconds is 5000 bytes.
• At 32 seconds, the traffic sample from 1 second is discarded, since it is older than the 30 seconds of the metric interval. The total traffic for the last 30 seconds is now 0.

The recompute interval works similarly. The server's recompute interval is 100ms.

Continuing with the example, the bandwidth is recomputed periodically every 100 milliseconds. The calculation is based on the amount of traffic as well as the metric interval.

• At 0 seconds, the bandwidth is calculated for the first time. The total traffic is zero, divided by the metric interval of 30 seconds, giving a bandwidth of zero.
• At 1 second, the bandwidth is calculated for the 10th time (1000 milliseconds/ 100 milliseconds). The total traffic is 5000 bytes, which is divided by 30 seconds. The bandwidth is 5000/30 = 166 bytes per second.
• At 30 seconds, the bandwidth is calculated for the 300th time. The total traffic is 5000 bytes, which is divided by 30 seconds. The bandwidth is 5000/30 = 166 bytes per second.
• At 32 seconds, the bandwidth is computed again for the 320th time. The traffic is now 0 (since the one connection that generated traffic is too old to be counted), divided by 30, giving a bandwidth of 0 bytes/second.

Configuring Quality of Service (QOS)

Quality of Service for a server instance or a class of virtual servers is configured through the Administration interface.

---

Note	To enforce your Quality of Service settings, you must also set up Server Application Functions (SAFs) in the obj.conf file as described in "Required Changes to the obj.conf File".

---

To configure Quality of Service, follow these steps:

1. Select the App Server Instances node in the left pane.
2. Expand the server instance node to display the HTTP Server node.
3. Click the HTTP Server node to display the QOS tab.
4. Click the QOS tab.

A following page displays the general settings for Quality of Service, followed by a properties button.

   Virtual Server Instance QOS Tab

5. To enable Quality of Service for this HTTP Server, click QOS Enable.

Note: By default, Quality of Service is disabled. Enabling Quality of Service slightly increases server overhead.

6. Specify the QOS Metrics Interval.

The metrics interval is the time period, in seconds, that data is sampled during server traffic calculations. The default value is 30 seconds.

If your site commonly has large file transfers, use a large value (several minutes or more) for this field. A large file transfer might take up all the allowed bandwidth for a short metric interval, and result in connections being denied if you've enforced the maximum bandwidth setting. Since the bandwidth is averaged by the metric interval, a longer interval smooths out spikes caused by large files.

If the bandwidth limit is much lower than available bandwidth (for example, 1 MB-per-second bandwidth limit but with a 1 GB-per-second connection to the backbone), the metric interval should be shortened.

Note: If you have large static file transfers and a bandwidth limit that is much lower than the available bandwidth, you must decide which situation to tune for, since the problems require opposite solutions.

7. Specify the QOS Recompute Time Interval.

The recompute time interval is the number of milliseconds between each computation of the bandwidth for all servers, classes, and virtual servers. The default is 100 milliseconds.

8. Specify the Bandwidth Limit.

This is the maximum bandwidth limit for the server instance in bytes per second. It is interdependent with the QOS Metrics Interval to some extent.

9. Choose whether or not to enforce the maximum bandwidth setting.

If you choose to enforce the maximum bandwidth, when the server reaches its bandwidth limit, additional connections are refused.

If you do not enforce the maximum bandwidth, when the maximum is exceeded, the server logs a message to the event log.

10. Specify the connection limit.

This is the number of concurrent requests processed.

11. Choose whether or not to enforce the connection limit setting.

If you choose to enforce the maximum connections, when the server reaches its limit, additional connections are refused. If you do not enforce the maximum connections, when the maximum is exceeded, the server logs a message to the event log.

12. (Optional). If specifying additional name-value pair attributes for Quality of Service, click the Properties button.

For a list of allowed name-value pairs for Quality of Service properties, refer to the online help.

13. Click Save to commit the changes to the server instance.
14. Access App Server Instances and your server instance in the left pane, then click Apply Changes.

Required Changes to the obj.conf File

To enforce Quality of Service, you must include directives in your obj.conf file to invoke following Server Application Functions (SAFs):

• AuthTrans qos-handler
• Error qos-error

In order to work properly, the qos-handler AuthTrans directive must be the first AuthTrans configured in the default object. The role of the Quality of Service handler is to examine the current statistics for the virtual server, virtual server class, and global server, and to enforce the limits by returning an error. The Sun ONE Application Server includes a built-in sample Quality of Service handler SAF, called qos-handler. This SAF logs when limits are reached, and returns a 503 Server busy error to the server so that it can be processed by the NSAPI.

The Sun ONE Application Server also includes a built-in sample error SAF called qos-error which returns an error page stating which limits caused the 503 error and the value of the statistic that triggered the limit.

For more information on these SAFs and how to use them, see the Sun ONE Application Server Developer's Guide to NSAPI.

Known Limitations to Quality of Service

When you use the Quality of Service features, keep in mind the following limitations:

• The Quality of Service features only measure the HTTP bandwidth at the application level. The HTTP bandwidth can differ from the actual TCP network bandwidth for a variety of reasons:

• If SSL is enabled, handshakes and client certificate exchanges add to the traffic but are not measured.
• If chunked encoding is enabled in either or both directions, the chunking layer removes the chunk headers and they are not counted in the traffic. Other headers or protocol items are counted.
• The Quality of Service features cannot accurately measure traffic from PR_TransmitFile calls. For basic I/O operations such as PR_Send()/net_write or PR_Recv()/net_read, the data transferred can be quickly accounted for by the bandwidth manager, since the number of bytes transferred in one system call is usually the size of a buffer and the I/O call returns quickly. This works very well to measure the instantaneous bandwidth of dynamic content applications. However, because the amount of data transferred from PR_TransmitFile is only known at the end of the transfer, it can't be measured before it completes.

If the PR_TransmitFile is short, then the Quality of Service features will perform adequately. However, If the PR_TransmitFile is long, as in the case of a long file downloaded by a dialup user, the whole amount of data transferred will be counted at completion time. When the bandwidth manager recomputes bandwidth after the next recompute interval period starts, the bandwidth computed will increase significantly because of that recent large PR_TransmitFile. This case could cause the server to deny all requests until the next metric interval, when the bandwidth manager will "expire" the transmit file operation (since it is too old) and thus the bandwidth value will go back down. If your site commonly has very long static file downloads, you should increase the metric interval from the default 30 seconds.

• The bandwidth computed is always an approximation because it is not measured instantaneously, but is recomputed at regular intervals and over a certain period. For example, if the metric interval is the default 30 seconds and the server is idle for 29 seconds, then the next second, a client could potentially use 30 times the bandwidth limit in one second.
• The Quality of Service bandwidth statistics are lost whenever the server is reconfigured dynamically. In addition, the Quality of Service limitations are not enforced in threads that have connections on an older, inactive configuration, because the bandwidth manager thread only computes bandwidth statistics for the active configuration. Potentially, a client that doesn't close its socket for a long time and remains active so that the server doesn't time it out would not be subject to the Quality of Service limitations after a dynamic server reconfiguration.
• The concurrent connections are computed with a different granularity for virtual servers than for virtual server classes and the global server instance. The connection counter for an individual virtual server is incremented atomically immediately after the request is parsed and routed to the virtual server. It is also decremented atomically at the end of the response processing for that request. This means that the virtual server connection statistics are always exact at any instant.

However, the connection statistics for the virtual server class and global server instance are not updated instantly. They are updated by the bandwidth manager thread every recompute interval. The connection count for the virtual server class is the sum of the connections on all virtual servers of that class; and the global server instance connection count is the sum of connections on all virtual server classes.

Because of the way these values are computed, the number of connections for a virtual server is always correct, and if you've enforced a limit to the number of connections, you can never have more than the limit. The virtual server class and server instance values are not quite as accurate, since they are only computed at intervals.

About SNMP

---

Simple Network Management Protocol (SNMP) is a protocol used to exchange management and monitoring information across a network. With SNMP, data travels between a managed device and a network management station (NMS). A managed device is anything that runs SNMP: hosts, routers, your HTTP server, and other servers on your network.

This section addresses the following topics:

• Network Management Station (NMS)
• Management Information Base (MIB) Objects
• SNMP Messages
• SNMP Trap Destinations
• SNMP Agent Community

Network Management Station (NMS)

The network management station (NMS) is a machine used to remotely manage a specific network. Usually, the NMS software will provide a graph to display collected data or use that data to make sure the server is operating within a particular tolerance.

The NMS is usually a powerful workstation with one or more network management applications installed. A network management application such as HP OpenView graphically shows information about managed devices, such as your HTTP servers. For example, it might show which servers in your enterprise are up or down, or the number and type of error messages received. When you use SNMP with the Sun ONE Application Server, this information is transferred between the NMS and the server through the use of two types of agents: the subagent and the master agent.

The subagent gathers information about the server instances running in various domains and passes the information to the master agent. There is a master agent and a subagent for every installation of the Sun ONE Application Server.

---

Note	After making any SNMP configuration changes, you must click the Apply button, then restart the SNMP subagent.

---

The master agent exchanges information between the various subagents and the NMS. The master agent is installed with the Sun ONE Application Server.

You can have multiple subagents installed on a host computer, but only one master agent. For example, if you had Sun ONE Directory Server, Sun ONE Application Server, and the Sun ONE Messaging Server installed on the same host, the subagents for each of the servers would communicate with the same master agent.

The NMS either requests information from the server or changes the value of a variable store in the server's MIB. For example:

1. The NMS sends a message to the Admin Server master agent. The message might be a request for data (a GET message), or an instruction to set a variable in the MIB (a SET message).
2. The master agent forwards the message to the appropriate subagent.
3. The subagent retrieves the data or changes the variable in the MIB.
4. The subagent reports data or status to the master agent, then the master agent forwards the message back (a GET message) to the NMS.
5. The NMS displays the data textually or graphically through its network management application.

Management Information Base (MIB) Objects

The Sun ONE Application Server stores variables pertaining to managing and monitoring information across a network. Variables the master agent can access are called managed objects. These objects are defined in a tree-like structure called the management information base (MIB). The MIB provides access to the HTTP server's network configuration, status, and statistics. Using SNMP, you can view this information from the network management workstation (NMS).

The top level of the MIB tree shows that the internet object identifier has the following subtrees:

• directory (1)
• mgmt (2)
• experimental (3)
• private (4)

The private (4) subtree contains the enterprises (1) node. Each subtree in the enterprises (1) node is assigned to an individual enterprise, which is an organization that has registered its own specific MIB extensions. An enterprise can then create product-specific subtrees under its subtree. MIBs created by companies are located under the enterprises (1) node.

Each Sun ONE Application Server subagent provides a MIB for use in SNMP communication. The server reports significant events to the NMS by sending messages or traps containing these variables. The NMS can query the server's MIB for data.

Each Sun ONE Application Server has its own MIB located at install_dir/lib

The Sun ONE Application Server's MIB is a file called appserv.mib. This MIB contains the definitions for various variables pertaining to network management for the Sun ONE Application Server.

The Sun ONE Application Server MIB has an object identifier of

appserver 1 (as appserver7 OBJECT IDENTIFIER ::= {appserver 1 }) and is located in the install_dir/lib directory.

You can see administrative information about your Sun ONE Application Server and monitor the server in real time using the Sun ONE Application Server MIB. The following table lists and describes the managed objects stored in the appserv.mib file.

   appserv.mib Managed Objects and Descriptions 

Managed object	Description
iwsCpuID	CPU identifier.
iwsCpuIdleTime	Idle CPU time.
iwsCpuKernelTime	CPU kernel time.
iwsCpuTable	Sun ONE Application Server CPUs.
iwsCpuUserTime	CPU user time.
iwsInstanceTable	Sun ONE Application Server instances.
iwsInstanceId	Server instance identifier
iwsInstanceVersion	String, such as SunONE-ApplicationServer-Enterprise/7 BB1-01/24/2001 17:15 (SunOS DOMESTIC)
iwsInstanceDescription	Description of the server instance.
iwsInstanceOrganization	Organization responsible for the server instance.
iwsInstanceContact	Contact information for person(s) responsible for server instance.
iwsInstanceLocation	Where the server is located.
iwsInstanceStatus	Status of the server instance.
iwsInstanceUptime	How long the server has been running.
iwsInstanceDeathCount	Number of times server instance processes have gone down.
iwsInstanceRequests	Number of requests processed by the server instance.
iwsInstanceInOctets	Number of octets received by the server instance. Will show 0 if information is not available.
iwsInstanceOutOctets	Number of octets transmitted by the server instance. Will show 0 if information is not available.
iwsInstanceCount2xx	Number of 200-level (Successful) responses issued by the server instance.
iwsInstanceCount3xx	Number of 300-level (Redirection) responses issued by the server instance.
iwsInstanceCount4xx	Number of 400-level (Client Error) responses issued by the server instance.
iwsInstanceCount5xx	Number of 500-level (Server Error) responses issued by the server instance.
iwsInstanceCountOther	Number of other (neither 2xx, 3xx, 4xx, nor 5xx) responses issued by the server instance.
iwsInstanceCount200	Number of 200 (OK) responses issued by the server instance.
iwsInstanceCount302	Number of 302 (Moved Temporarily) responses issued by the server instance.
iwsInstanceCount304	Number of 304 (Not Modified) responses issued by the server instance.
iwsInstanceCount400	Number of 400 (Bad Request) responses issued by the server instance.
iwsInstanceCount401	Number of 401 (Unauthorized) responses issued by the server instance.
iwsInstanceCount403	Number of 403 (Forbidden) responses issued by the server instance.
iwsInstanceCount404	Number of 404 (Not Found) responses issued by the server instance.
iwsInstanceLoad1MinuteAverage	1 minute load average of the system running the server instance.
iwsInstanceLoad5MinuteAverage	5 minute load average of the system running the server instance.
iwsInstanceLoad15MinuteAverage	15 minute load average of the system running the server instance.
iwsInstanceNetworkInOctets	Number of octets transmitted on the network per second.
iwsInstanceNetworkOutOctets	Number of octets received on the network per second.
iwsVsTable	Server virtual servers.
iwsVsId	Virtual server identifier.
iwsVsRequests	Number of requests processed by the virtual server.
iwsVsInOctets	Number of octets received by the virtual server.
iwsVsOutOctets	Number of octets transmitted by the virtual server.
iwsVsCount2xx	Number of 200-level (Successful) responses issued by the virtual server.
iwsVsCount3xx	Number of 300-level (Redirection) responses issued by the virtual server.
iwsVsCount4xx	Number of 400-level (Client Error) responses issued by the virtual server.
iwsVsCount5xx	Number of 500-level (Server Error) responses issued by the virtual server.
iwsVsCountOther	Number of other (neither 2xx, 3xx, 4xx, nor 5xx) responses issued by the virtual server.
iwsVsCount200	Number of 200 (OK) responses issued by the virtual server.
iwsVsCount302	Number of 302 (Moved Temporarily) responses issued by the virtual server.
iwsVsCount304	Number of 304 (Not Modified) responses issued by the virtual server.
iwsVsCount400	Number of 400 (Bad Request) responses issued by the virtual server.
iwsVsCount401	Number of 401 (Unauthorized) responses issued by the virtual server.
iwsVsCount403	Number of 403 (Forbidden) responses issued by the virtual server.
iwsVsCount404	Number of 404 (Not Found) responses issued by the virtual server.
iwsProcessTable	Sun ONE Application Server processes.
iwsProcessId	Operating system process identifier.
iwsProcessThreadCount	Number of request processing threads.
iwsProcessThreadIdle	Number of request processing threads currently idle.
iwsProcessConnectionQueueCount	Number of connections currently in connection queue.
iwsProcessConnectionQueuePeak	Largest number of connections that have been queued simultaneously.
iwsProcessConnectionQueueMax	Maximum number of connections allowed in connection queue.
iwsProcessConnectionQueueTotal	Number of connections that have been accepted.
iwsProcessConnectionQueueOverflows	Number of connections rejected due to connection queue overflow.
iwsProcessKeepaliveCount	Number of connections currently in keepalive queue.
iwsProcessKeepaliveMax	Maximum number of connections allowed in keepalive queue.
iwsProcessSizeVirtual	Process size in kilobytes.
iwsProcessSizeResident	Process resident size in kilobytes.
iwsProcessFractionSystemMemoryUsage	Fraction of process memory in system memory.
iwsListenTable	Sun ONE Application Server listen sockets.
iwsListenId	Listen socket identifier.
iwsListenAddress	Address where socket listens.
iwsListenPort	Port where socket listens.
iwsListenSecurity	Encryption support.
iwsThreadPoolCount	Number of requests denied.
iwsThreadPoolMax	Maximum number of requests allowed in queue.
iwsThreadPoolPeak	Largest number of requests that have been queued simultaneously.
iwsThreadPoolTable	Sun ONE Application Server thread pools.
iwsVsCount503	Number of 503 (Unavailable) responses issued.
iwsInstanceCount503	Number of 503 (Unavailable) responses issued.

SNMP Messages

GET and SET are two types of messages defined by SNMP.

Each object is assigned a unique identifier within the MIB. Objects are accessed by the SNMP Manager by issuing GET and GETNEXT commands which specify the object's unique identifier. The Proxy Agent obtains the value of the specified object and transmits it to the SNMP manager. Events added to the log may generate SNMP traps provided they satisfy trap filter conditions. Events that do not generate traps are merely recorded as an entry in the maintenance log table and are accessed by the SNMP Manager through normal GET and GETNEXT commands.

GET and SET messages are sent by a network management station (NMS) to a master agent. You can use one or the other, or both, through the Administration interface.

SNMP exchanges network information in the form of protocol data units (PDUs). These units contain information about variables stored on the managed device, such as the HTTP server. These variables, also known as managed objects, have values and titles that are reported to the NMS as necessary. Protocol data units sent by the server to the NMS are known as traps. The use of GET, SET, and trap messages are explained further in the following sections.

SNMP Trap Destinations

An SNMP trap is a message the SNMP agent sends to a network management station (NMS). For example, an SNMP agent sends a trap when the status of an interface has changed from up to down. The SNMP agent must know the address of the NMS so it knows where to send traps.

You can configure this trap destination for the SNMP master agent from the Sun ONE Application Server Administration interface. You can also view, edit, and remove the trap destinations you have already configured. When you configure trap destinations using the Administration interface, you are actually editing the CONFIG file.

The server subagent sends a message or trap to the NMS when a significant event has occurred. For example:

1. The subagent informs the master agent that the server has stopped.
2. The master agent sends a message, or trap, reporting the event to the NMS.
3. The NMS displays the information textually or graphically through its network management application.

Refer to "Installing the SNMP Master Agent" for instructions on setting up the SNMP trap port.

SNMP Agent Community

The SNMP agent community consists of a community string and the operations assigned to the specified community. The community string is a text string for a network management station (NMS) name that an SNMP agent uses for authorization. This means that an NMS would send a community string with each message it sends to the agent.

The operations assigned are get and/or set. The SNMP agent can then verify whether the NMS is authorized to perform get, set, or both get and set operations for data exchange. Community strings are not concealed when sent in SNMP packets; strings are sent in ASCII text.

You can configure and manage the community string and the allowed operations for each specified community from the Administration interface. Refer to "Installing the SNMP Master Agent" for instructions on setting up the SNMP Agent Community.

Setting Up SNMP

---

In general, to use SNMP, a master agent and at least one subagent must be installed and running on your system. The master agent must be installed before you can enable a subagent. Refer to "Installing the SNMP Master Agent".

The procedures for setting up SNMP are different depending upon your system. The following table provides an overview of procedures to follow for different situations. The actual procedures are described in detail later in the chapter.

If your server meets these conditions...	...follow these procedures. (discussed in detail in the following sections).
No native agent is currently running	Start the master agent. Enable the subagent for each server installed on the system.
Native agent is currently running No SMUX No need to continue using native agent	Stop the native agent when you install the master agent for your Administration Server. Start the master agent. Configure the SNMP subagent for each server instance.
Native agent is currently running No SMUX Needs to continue using native agent	Install a proxy SNMP agent. Start the proxy SNMP agent. Restart the native agent using a port number other than the master agent port number. Start the master agent. Enable the subagent for each server installed on the system.

Before you begin, you should verify two things:

• Is your system already running an SNMP agent (an agent native to your operating system)?
• If so, does your native SNMP agent support SMUX communication?

See your system documentation for information on how to verify this information.

---

Note	After changing SNMP settings in the Admin Server, installing a new server, or deleting an existing server, you must perform the following steps: (Windows 2000) Restart the Windows SNMP service or reboot the machine. (UNIX) Restart the SNMP master agent and the SNMP subagent using the Admin Server.

---

The following topics are addressed in this section:

• Using a Proxy SNMP Agent (UNIX/Linux)
• Installing the SNMP Master Agent

Using a Proxy SNMP Agent (UNIX/Linux)

You need to use a proxy SNMP agent when you already have a native agent running, and you want to continue using it concurrently with a Sun ONE Application Server master agent. Before you start, be sure to stop the native master agent. (See your system documentation for detailed information.)

---

Note	To use a proxy agent, you'll need to install it and then start it. You'll also have to restart the native SNMP master agent using a port other than the port the Sun ONE Application Server master agent is running on.

---

This section includes the following topics:

• Installing the Proxy SNMP Agent
• Starting the Proxy SNMP Agent
• Restarting the Native SNMP Daemon

Installing the Proxy SNMP Agent

If an SNMP agent is running on your system and you want to continue using the native SNMP daemon, follow the steps in these sections:

1. Install the SNMP master agent. See "Installing the SNMP Master Agent".
2. Install and start the proxy SNMP agent and restart the native SNMP daemon. See "Using a Proxy SNMP Agent (UNIX/Linux)".
3. Start the SNMP master agent. See "Enabling and Starting the SNMP Master Agent".
4. Enable the subagent. See "Enabling the Subagent".

To install the SNMP proxy agent, edit the CONFIG file (you can give this file a different name), located in install_dir/lib/snmp/sagt in the server root directory, so that it includes the listening port for the SNMP daemon. The proxy agent also needs to include the MIB trees and traps that the proxy SNMP agent will forward.

Here is an example of a CONFIG file:

AGENT AT PORT 1161 WITH COMMUNITY public    SUBTREES             1.3.6.1.2.1.1,                1.3.6.1.2.1.2,                1.3.6.1.2.1.3,                1.3.6.1.2.1.4,                1.3.6.1.2.1.5,                1.3.6.1.2.1.6,                1.3.6.1.2.1.7,                1.3.6.1.2.1.8    FORWARD ALL TRAPS;

Starting the Proxy SNMP Agent

To start the proxy SNMP agent, enter the following at the command prompt:

# sagt -c CONFIG&

Restarting the Native SNMP Daemon

After starting the proxy SNMP agent, restart the native SNMP daemon at the port you specified in the CONFIG file.

To restart the native SNMP daemon, enter the following at the command prompt:

# snmpd -P port_number

where port_number is the port number specified in the CONFIG file. For example, on the Solaris platform, using the port in the previously mentioned example of a CONFIG file, you would enter:

# snmpd -P 1161

Installing the SNMP Master Agent

---

Note	You cannot use the Administration interface to install and start the master SNMP agent unless the server is running as root.

---

To install the master SNMP agent:

1. Log in as root.
2. Check whether an SNMP daemon (snmpd) is running on port 161.

If no SNMP daemon is running, go to Step 4.

If an SNMP daemon is running, make sure you know how to restart it and which MIB trees it supports.

3. If an SNMP daemon is running, kill its process.
4. In the Administration interface, select the Admin Server node from the left pane.
5. Select the Monitoring tab to display the SNMP Agent Trap page, as shown in the following figure:

   SNMP Agent Trap Page

The Manager Entries information is displayed on this page.

6. Type the name of the system that is running your network management software.
7. Type the trap port number at which your network management system listens for traps. (The well-known port is 162.) For more information on traps, see "SNMP Trap Destinations".
8. Type the community string you want to use in the trap. For more information on community strings, see "SNMP Agent Community".
9. Click OK.
10. Click the SNMP Agent Community link within the Monitoring tab.

The Community Strings information is displayed, as shown in the following figure.

   SNMP Agent Community Page

11. Type the community string for the master agent.
12. Choose an operation level for the community.

After you establish a community, you can edit its settings or remove it from the buttons indicated within the Current Communities heading on this page.

13. Click OK.
14. Access App Server Instances and your server instance in the left pane, then click Apply Changes.

Enabling and Starting the SNMP Master Agent

---

Master agent operation is defined in an agent configuration file named CONFIG, which you can edit manually. You must install the master SNMP agent before you can enable the SNMP subagent.

---

Note	If you get a bind error similar to System Error: Could not bind to port when restarting the master agent, use ps -ef | grep snmp to check if magt is running. If it is running, use the command kill -9 pid to end the process. The CGIs for SNMP will then start working again.

---

This section includes the following topics:

• Starting the Master Agent on Another Port
• Manually Configuring the SNMP Master Agent
• Editing the Master Agent CONFIG File
• Defining sysContact and sysLocation Variables
• Configuring the SNMP Master Agent
• Starting the SNMP Master Agent
• Enabling the Subagent

Starting the Master Agent on Another Port

The Administration interface will not start the SNMP master agent on ports other than 161. However, you can manually start the master agent on another port using the following steps:

1. Edit install_dir/lib/snmp/magt/CONFIG to specify the desired port.
2. Run the start script as follows:

cd instance_root/admin-server ./start -shell install_dir/lib/snmp/magt/magt
install_dir/lib/snmp/magt/CONFIG
install_dir/lib/snmp/magt/INIT

The master agent will then start on the desired port. However, the Administration interface will be able to detect that the master agent is running.

Manually Configuring the SNMP Master Agent

To configure the master SNMP agent manually:

1. Log in as root.
2. Check to see if there is an SNMP daemon (snmpd) running on port 161.

If an SNMP daemon is running, make sure you know how to restart it and which MIB trees it supports. Then kill its process.

3. Edit the CONFIG file located in lib/snmp/magt in the server root directory.
4. (Optional) Define sysContact and sysLocation variables in the CONFIG file as described in "Defining sysContact and sysLocation Variables".

Editing the Master Agent CONFIG File

The CONFIG file defines the community and the manager that will work with the master agent. The manager value should be a valid system name or an IP address.

Here is an example of a basic CONFIG file:

COMMUNITY          public                    ALLOW ALL OPERATIONS MANAGER            manager_station_name                    SEND ALL TRAPS TO PORT 162                     WITH COMMUNITY public

Defining sysContact and sysLocation Variables

You can edit the CONFIG file to add initial values for sysContact and sysLocation which specify the sysContact and sysLocation MIB-II variables. The strings for sysContact and sysLocation in this example are enclosed in quotes. Any string that contains spaces, line breaks, tabs, and so on must be in quotes. You can also specify the value in hexadecimal notation.

Here is an example of a CONFIG file with sysContact and sysLocation variables defined:

COMMUNITY          public                    ALLOW ALL OPERATIONS MANAGER            nms2                    SEND ALL TRAPS TO PORT 162                    WITH COMMUNITY public INITIAL            sysLocation "Server room 901 San Antonio Road Palo Alto CA 94303 USA" INITIAL            sysContact "John Doe email: jdoe@sun.com"

Configuring the SNMP Subagent

To configure the SNMP subagent, perform the following steps:

1. From the Admin Server, select the server instance node in the left pane.
2. Select the Monitoring tab from the right pane.
3. Select the SNMP Subagent Configuration link.

The following page is displayed:

   SNMP Subagent Configuration Page

4. (UNIX only) Enter the name and domain of the server in the Master Host field.
5. Enter the Description of the server, including operating system information.
6. Enter the Organization responsible for the server.
7. Enter the location of the server instance.
8. Enter the name of the person responsible for the server and the person's contact information in the Contact field.
9. Select On to Enable the SNMP Statistics Collection.
10. Click OK.
11. Access App Server Instances and your server instance in the left pane, then click Apply Changes.

Starting the SNMP Master Agent

Once you have installed the SNMP master agent, you can start it manually or by using the Admin Server from the Administration interface.

Manually Starting the SNMP Master Agent

To start the master agent manually, enter the following at the command prompt:

# magt CONFIG INIT&

The INIT file is a nonvolatile file that contains information from the MIB-II system group, including system location and contact information. If INIT doesn't already exist, starting the master agent for the first time will create it.

---

Note	An invalid manager name in the CONFIG file will cause the master agent start-up to fail.

---

To start a master agent on a non-standard port, use one of two methods:

Method 1: In the CONFIG file, specify a transport mapping for each interface over which the master agent listens for SNMP requests from managers. Transport mappings allow the master agent to accept connections at the standard port and at a non-standard port. The master agent can also accept SNMP traffic at a non-standard port. The maximum number of concurrent SNMP is limited by your target system's limits on the number of open sockets or file descriptors per process. Here is an example of a transport mapping entry:

TRANSPORT          extraordinary   SNMP
                   OVER UDP SOCKET
                    AT PORT 11161

After editing the CONFIG file manually, you should start the master agent manually by typing the following at the command prompt:

# magt CONFIG INIT&

Method 2: Edit the /etc/services file to allow the master agent to accept connections at the standard port as well as at a non-standard port.

Starting the SNMP Master Agent Using the Admin Server

To start the SNMP master agent using the Admin Server, perform the following steps:

---

Note	You must be logged in the Sun ONE Application Server as root to start the SNMP Master Agent.

---

1. Log in to the Admin Server.
2. From the Admin Server node in the left pane, choose the Monitoring tab.
3. Choose the SNMP Agent Control link near the top of the right pane.

The following page is displayed.

   SNMP Agent Control Page

4. Click Start.

You can also stop and restart the SNMP master agent from the SNMP Agent Control page.

Enabling the Subagent

After you have installed the master agent that comes with the Administration Server, you must enable the subagent for your server instance before you attempt to start it. For information on installing the master agent, see "Installing the SNMP Master Agent".

You can use the subagent to stop the SNMP function on UNIX/Linux platforms. You must stop the subagent first, then the master agent. If you stop the master agent first, you may not be able to stop the subagent. If that happens, restart the master agent, stop the subagent, then stop the master agent.

To enable the SNMP subagent:

1. Expand the App Server Instances node in the left pane.
2. Select the server instance, then click the Monitoring tab.
3. Select the SNMP Subagent Control option to display the page as shown in the following figure.

   SNMP Subagent Control Page

From this page, you can start, stop, or restart the SNMP subagent. The status of the subagent is indicated just above the control buttons.

On the Windows platform, the Windows SNMP service is used for monitoring the Sun ONE Application Server; it can be controlled from the Control Panel/Administrative Tools/Services option.

---

Note	After making any SNMP configuration changes, you must click OK, then restart SNMP subagent from the SNMP Subagent Control page.

---