Академический Документы
Профессиональный Документы
Культура Документы
This document describes the setup and operation of the communication channels
used within the Hyperic HQ product. This includes setup of the server and agent,
as well as description of how data is passed between the various HQ
components. For readability, the classes referenced in this document that are
part of the HQ package are highlighted in bold italics. References to
<subsystem> should be replaced with one of the subsystems within HQ. (control,
measurement, rt, etc)
Server Configuration
Port Purpose
7080 HTTP
7443 HTTPS
9009 AJP Connector
2098 RMI
2099 JNP
7444 RMI Object Port
7445 ServerBindPort
9093 ServerBindPort
All inbound communication to the HQ server from agents is done through the
web container listening on either 7080 for HTTP or 7443 for HTTPS. The port
that is used is determined when the agent setup is run. All requests from the
agents are processed by the jboss-lather web application.
The JNP and RMI ports are used by the HQ shell to execute methods on the
server using the server’s remote EJB interfaces.
Agent Configuration
Hyperic Confidential
All communication to the agent through port 2144 is encrypted using SSL, and
connections are authenticated using a shared secret that is established when the
agent is first setup.
To aid in setups where firewalls are an issue, the HQ agent setup process will
ask for the IP address for the server to contact the agent at, in case this is a
different IP address than the agent is binding to.
Server/Agent Communication
Within HQ there are 2 types of communication between the agent and server.
Server initiated communication are the agent commands, and are usually
initiated through the UI or through the HQ Shell. These commands include
running control actions and scheduling metrics among others. The protocol for
sending the commands is fairly primitive. The command is sent in raw TCP/IP
over SSL to the agent daemon.
Type Purpose
Integer API Version
Integer Command Version
String Command Name
String Key1
String Value1
String Key2
String Value2
… …
Within HQ many of the types we send over the wire have their own serialization
methods. Examples of this are the ConfigReponse and ConfigSchema
classes. For other objects standard Java serialization can be used to obtain a
Hyperic Confidential
byte representation of the object, which can then be converted to a String using
Hyperic’s Base64 encoder. Base64 is used for conversion to String mainly for
speed, but it’s symmetric properties make it a good choice for encoding and
decoding Strings.
os.writeObject(properties);
propStr = Base64.encode(bs.toByteArray());
super.setValue(PROP_PROPERTIES, propStr);
} catch (IOException e) {
} catch (EncodingException e) {
} finally {
try {os.close();}
catch (Exception ex) {}
}
}
res = (Properties)os.readObject();
return res;
} catch (IOException e) {
} catch (EncodingException e) {
}
}
Hyperic Confidential
subclasses of AgentRemoteValue in the
net.hyperic.hq.<subsystem>.agent.commands package.
Now that argument and result object processing is understood, the next topic is
the client classes that are used to invoke the methods on the agent. In HQ these
classes are named <Subsystem>CommandsClient, and are found in the
net.hyperic.hq.<subsystem>.client package. The client classes have methods for
each command that is available for that subsystem within the agent. These
methods simply wrap up the arguments into a AgentRemoteValue and call the
agent using the sendCommand() method in the AgentConnection class.
This document is meant to illustrate the sending data to and from the server. For
more information on extending the HQ agent see the document Hyperic HQ
Agent.doc.
Important: Note that the HQ agent uses a single accept model. This means that
the command is sent to the agent using the client class, then blocks waiting for
the return object. For methods that may take a considerable time on the agent,
it’s advisable to return a NullLatherValue and report the results back to the
server asynchronously using an agent call back into the server. This method is
described below.
Agent initiated commands are used by the agent to send data back to the server.
The most common case in HQ is the sending of measurement data back to the
server. Another use of agent initiated commands is to send back the result of an
agent command that may take a while to complete. An example of this is a
control action, or an auto-discovery scan.
Hyperic Confidential
Commands sent to the server are sent to the jboss-lather servlet running inside
the HQ server using a POST over HTTP or HTTPS. Within HQ all subclasses of
LatherValue can be found in the net.hyperic.hq.bizapp.shared.lather package.
The use of these classes to pass and return values is similar to that of the
AgentRemoteValue class. Like AgentRemoteValue, each parameter should
have a get() and set() method to abstract out the storage implementation.
Just like server to agent communication, the agent to server communication also
involves a set of client classes to send the command to the server. These
classes follow the naming pattern <Subsystem>CallbackClient. They can be
found in the net.hyperic.hq.bizapp.client package.
Hyperic Confidential