Set Up Agent Interactively

About this page...

This page has instructions for interactively configuring a newly installed Hyperic Agent to communicate with the Hyperic Server, or reconfiguring the communication behavior of an existing agent.

Before following the instructions below, see Hyperic Installation and Startup Process to see how agent configuration fits into the overall Hyperic implementation process and to understand agent configuration options and requirements.

Depending upon your situation, it may be preferable to configure agent-server communication settings in the agent's agent.properties file, rather than interactively:

About the Agent Configuration Dialog

The agent configuration dialog appears in the shell when you launch a Hyperic Agent that lacks the configuration values that specify the location of the Hyperic Server. The dialog queries for the address and port of the Hyperic server, and other connection-related data. To understand the details of how the agent figures out where to contact the Hyperic Server see What Happens When an Agent Starts Up on About the Agent Launcher and Agent Startup.

The agent configuration dialog is presented in these cases:

  • The first time you start an agent (assuming that have not supplied the properties in agent.profile).

  • When you start an agent that whose saved server connection data is corrupt or has been removed.

  • When you run the agent launcher with the setup option, which causes the agent to prompt for new connection property settings.

You can also run the agent launcher with the to re-run the configuration dialog

Launch the Configuration Dialog

  1. Open a terminal window on the platform where the agent is installed.

  2. Navigate to the AgentHome/bin directory.

  3. Run the agent launcher with the start or setup option:

    • On Unix-like platforms:

      sh hq-agent.sh start
    • On Windows platforms, install the Windows service for the agent, and then start it:

      sh hq-agent.bat install
      sh hq-agent.bat start
  4. Respond to the prompts described below in Agent Configuration Dialog.

Agent Configuration Dialog

  1. Should Agent communications to HQ be unidirectional [default=no]

  2. What is the HQ server IP address

    • Enter the listen address of your Hyperic Server. The server must be running. If the server is on the same machine as the agent, you can enter localhost.

    • If there is a firewall blocking traffic from the agent to the server, specify the address of the firewall.

  3. Should Agent communications to HQ always be secure [default=yes].

    • Accept the default to configure Hyperic to use SSL for agent-to-server communication. (Server-agent communication is always SSL.)

    • SSL configuration is strongly recommended, and required if you configured unidirectional communications in Step 1.

    • To configure Hyperic to use plain HTTP for agent-to-server communication, enter "no".

  4. You are prompted to identify the server port where the Hyperic server listens for agent communication. Depending on whether you selected SSL in the previous step, one of the following prompts appears:

    • What is the secure HQ server port [default=7443] — If the Hyperic Server is configured to listen for SSL communications on the default SSL port of 7443, press Return.

    • What is the HQ server port [default=7080] — If the Hyperic Server is configured to listen on the default port of 7080, press Return. If there is a firewall blocking traffic from the agent to the server, configure it to forward traffic on TCP port 7080 (or 7443) to the host running the Hyperic Server.

  5. What is your HQ login [default=hqadmin]:

    • By default, the Hyperic Server is initially configured with an administrative account with username hqadmin. Unless you have configured a different Hyperic user account for agent-server communications, accept the default.

  6. What is your HQ password

    • Enter the password for the username you supplied at the previous prompt.

  7. What IP should HQ use to contact the agent [default=n.n.n.n]

    • The prompt will show the first IP address the agent detects on the host.

    • If there is another IP address on the host you prefer to use, enter it.

    • If there is a firewall blocking traffic from the server to the agent, enter the IP address of the firewall, and configure the firewall to forward traffic intended for the Hyperic Agent to the listen address of the agent host.

  8. What port should HQ use to contact the agent [default=2144]

    • Enter the agent port the Hyperic Server should use when it initiates contact with the agent. Specify the port that the agent binds to at startup, which by default is 2144.

    • If you have previously edited agent.properties to explicitly define a different listen port, using the optional agent.listenPort property, that is the value you should supply to this prompt.

    • If there is a firewall blocking traffic from the server to the agent, configure the device to forward traffic on TCP port 2144 to the Hyperic Agent.

  9. After you respond to the last prompt the agent initiates a connection to the server and the server verifies that it can communicate with the agent.

    If you have not configured user-managed keystores on the agent and server the agent will issue warning related to the components' self-signed SSL certificates. For more information see the SSL Warnings note on Hyperic Installation and Startup Process.

    • Once the agent and server successfully establish communication and complete the registration process, messages similar to the following appear:

      Received temporary auth token from agent
      Registering agent with HQ
      HQ gave us the following agent token
      1215038691323-8570363106994871928-8259195015465958356
      Informing agent of new HQ server
      Validating
      Successfully setup agent
  10. The Hyperic Agent discovers the platform and supported products running on it. For more information, see the Import discovered resources step on Hyperic Installation and Startup Process.