TOC PREV NEXT

HipCheck Mobility Service HipCheck Installation and User Guide

5 Managing HipCheck agents

This chapter describes the various tasks that you can perform to manage the HipCheck agents that are running on supported SCO UNIX and Microsoft Windows systems.

Specifically, this chapter covers:

Managing the HipCheck agent on SCO UNIX systems

The HipCheck agent for SCO UNIX systems is a service that starts automatically upon installation, and whenever the system is restarted.
Note: The HipCheck agent for SCO UNIX must run as root, so it can execute the necessary system commands for monitoring the system and for responding to actions from HipCheck clients.

Management tasks covered in this section include:

Checking status and troubleshooting problems

To check on the status of a HipCheck agent running on an SCO UNIX system:

Extending the HipCheck agent

The HipCheck agent for SCO UNIX systems can be extended to provide custom application monitoring. The agent includes a tool called svcmon, which allows you to define your own applications as services that can be monitored and managed by the HipCheck mobility service.

The HipCheck agent uses the svcmon tool to monitor the status of UNIX services, and to start, stop, enable, and disable services when an action request is received from a HipCheck client. Additionally, the svcmon tool includes a template file that you can use to extend the HipCheck agent to monitor and manage custom services, processes, or daemons. This template includes pre-defined variables and functions, to help make it easy and fast to add a new service.

This file is called template and is located in the /usr/lib/svcmon.d/services directory.

To set up your own service for HipCheck monitoring:

  1. Choose a name for your new service. Make a copy of the /usr/lib/svcmon.d/services/template file, assigning it the service name that you selected and placing it in the system release directory that corresponds to your operating system. The svcmon system release directories are:
    • /usr/lib/svcmon.d/services/Legend -- for OpenServer Release 6
    • /usr/lib/svcmon.d/services/SCO_SV -- for OpenServer Release 5.0.7
    • /usr/lib/svcmon.d/services/UnixWare -- for UnixWare 7.1.4
    When svcmon runs, it checks to see which platform it's running on and it uses the services under the appropriate directory. For example, to create a new SCO UnixWare 7.1.4 service called dbserv, you would do the following: 
    # cd /usr/lib/svcmon.d/services

# cp template UnixWare/dbserv
  2. Edit your new service file, modifying the template's contents so it is specific to your service.
    • The template uses "servone" as a placeholder for the service name. Do a global search and replace to change "servone" to the name of your service. Using the example above, you would replace "servone" with "dbserv".
      If you are using vi, you can do the search and replace by entering: 
      :%s/servone/dbserv/g
    • If your service already has a start/stop script, reference it with the provided variable, servone_init_cmd -- or, in the case of the example, now called dbserv_init_cmd: 
      dbserv_init_cmd="/etc/init.d/dbserv"
      If you do not have a start/stop script, fill in the appropriate functions provided by the framework in the template. This may require some shell programming.
  3. When you are finished, save your changes and exit the service file.
  4. A test service, called sample, is provided as an example. You can use this example to experiment with integrating a custom service into svcmon, as well as to perform service testing. A copy of the sample service is provided in each of the system release directories in /usr/lib/svcmon.d/service. This example service can be enabled, started, stopped, and so forth. Associated shell scripts run from /usr/lib/svcmon.d/test/sample/. To start the sam[ple service, enter: 
    # svcmon enable sample

See also:

Removing the HipCheck agent

To remove the HipCheck agent from an SCO OpenServer Release 5.0.7 or Release 6 system, log in as root and run: 

# custom -p SCO:HipcheckSCOUnixAgent -r

To remove the HipCheck agent from an SCO UnixWare system, log in as root and run: 

# pkgrm HcSCOUA

Managing the HipCheck agent on Windows systems

The HipCheck agent for SCO Windows systems is a service that starts automatically upon installation, and whenever the system is restarted.

Management tasks covered in this section include:

Checking status and troubleshooting problems

To check on the status of a HipCheck agent running on a Windows system:

  1. Open Control Panel > Administrative Tools > Services.
  2. Locate the HipCheck Agent entry in the list of services. The "Status" column indicates if the agent is running or not.
  3. If needed, you can stop and restart the service, using the links in the left panel, or by double-clicking on the HipCheck Agent entry.
  4. The HipCheck agent stores detailed information in a custom event log. To check this HipCheck log for problems:
a. Open the Control Panel, double-click Administrative Tools, and then double-click Event Viewer.
b. Double-click the HipcheckLog entry.
c. If you have problems getting a HipCheck agent to run, check the HipCheck log for error messages that indicate why the agent is unable to start. This problem is often caused by another product using the TCP/IP port that the HipCheck agent is trying to use. To correct this, edit the Windows registry to configure the HipCheck agent to use a different port, as described in "Configuring the HipCheck agent".
To control the level of detail that is tracked in the HipCheck event log, see "Monitoring and debugging the HipCheck agent".

Note that Windows automatically stops adding entries to log files that reach 2MB in size. Therefore, periodic clearing of the HipCheck event log using Event Viewer is recommended.

Configuring the HipCheck agent

When you install the HipCheck agent, you can specify the TCP/IP port on which the agent listens for requests from HipCheck clients, as well as the frequency with which the agent should check for alert conditions. The default settings are port 8081 and a poll interval of 30 seconds.

If you need to change either of these settings after installing the HipCheck agent, run regedit and edit these Windows registry keys: 

HKEY_LOCAL_MACHINE\SOFTWARE\Me Inc\Hipcheck\Port

HKEY_LOCAL_MACHINE\SOFTWARE\Me Inc\Hipcheck\PollTime

After you edit these registry keys, restart the HipCheck agent so the new settings take effect.
Important: See your Windows documentation for information on editing the Windows registry. If you edit the registry incorrectly, you may severely damage your system. It is a good idea to export the keys in the registry that you plan to edit, or back up the complete registry, before making any changes.

You must also log in to the HipCheck Portal and update the information for this system so that the agent's web address includes the new TCP/IP port number. HipCheck clients will not be able to connect to this agent until you supply this information. See "Manage the HipCheck system monitoring list" in Chapter 4, "Managing HipCheck systems and users" for help updating system information. The HipCheck Portal is available at:

https://<CommName>.hipcheck.me-inc.com/hipcheck/app

where <CommName> is the Community Name for your Me Inc. account.

Monitoring and debugging the HipCheck agent

The following Windows registry keys are provided so that you can monitor and debug a HipCheck agent running on a Windows system:


By default, all HipCheck requests received by the agent and every alert condition that is triggered is written to the HipCheck event log, HipcheckLog. To restrict logging so that only agent start, stop, and error messages are stored in the event log, edit the LogAccess registry key and turn it off by setting the value to "0".

To track debugging messages in the HipCheck event log, HipcheckLog, edit the Debug registry key and turn it on by setting the value to "1". Agent debugging is turned off by default.
Important: See your Windows documentation for information on editing the Windows registry. If you edit the registry incorrectly, you may severely damage your system. It is a good idea to export the keys in the registry that you plan to edit, or back up the complete registry, before making any changes.

If you edit either of these registry keys, restart the HipCheck agent so that the new settings take effect.

Note that Windows automatically stops adding entries to log files that reach 2MB in size. Therefore, periodic clearing of the HipCheck event log is recommended. See "Checking status and troubleshooting problems" for information on using the Windows Event Viewer to access HipcheckLog.

Removing the HipCheck agent

To remove the HipCheck agent from a Windows system:

  1. Open Control Panel > Administrative Tools > Services.
  2. Double-click the HipCheck Agent entry and then select Stop to stop the agent.
  3. Also from the Control Panel, run Add/Remove Programs and remove HipCheck Agent for Windows.

Configuring the proxy, https, and certificates

The "Create New System" and "Modify Attributes" pages at the HipCheck Portal allow you to specify one of four agent connection types, three of which can be configured to use https (encrypted) connections with certificate exchange.

These instructions discuss the Agent Connection Type options in the order they are presented in the administrative interface, which is also the order of increasing security.

Direct through http

This is the default connection type, and is appropriate for evaluation, development, and testing of HipCheck, but not for production use. For SCO-hosted HipCheck services, all systems being monitored must be located outside of any firewalls (i.e., directly accessible via the Internet) in order to use this connection type. Typically, a non-critical system is located outside the company firewall in order to test agent functionality.

This connection type can be used with either the http or https protocols; https is recommended. To set up agent systems for use with https, follow the instructions in these sections, below:

Through proxy

The Proxy Agent Relay's purpose is to provide a relay service between the HipCheck Mobility Server (MS) and one or more systems running agents behind a firewall. This allows for a single point of access for each system running an agent. The concept is illustrated in the following diagram:



One port is configured in the firewall to let the MS machine talk to the proxy machine. SOAP calls from the MS to an agent go instead from the MS to the Proxy, where they are relayed to any number of machines inside the Intranet.

Note that Agent-to-MS messages don't go through the proxy; they go (by default) over port 8080 directly back to the MS.

Using a proxy server requires the following setup, detailed in the following sections:

Setting up Tomcat SSL encryption
  1. Create a directory for the certificate information. This document assumes that the files for certificate creation will be located in /.cert. 
    # mkdir /.cert
  2. Enter the following at a shell prompt: 
    # JAVA_HOME=/usr/java

# export JAVA_HOME

# TOMCAT=/usr/lib/apache/tomcat

# export TOMCAT

# CERT=/.cert

# KT=${JAVA_HOME}/bin/keytool
  3. Edit $TOMCAT/conf/server.xml. Find the (commented out) <Connector...> tag that directly follows the comment: 
    <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
    This connector deals with handling secure SSL connections. Uncomment this <Connector...> tag and edit it to read as shown:
<Connector
className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8443" minProcessors="5" maxProcessors="75"
enableLookups="true" acceptCount="100"
debug="0" scheme="https" secure="true"
useURIValidationHack="false" disableUploadTimeout="true">
<Factory
className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
keystoreFile="/.certs/tomcat.keystore"
keystorePass="changeit"
clientAuth="false" protocol="TLS" />
</Connector>
Setting Up a Self-Signed Certificate

The self-signed certificates created here are installed on the system running the HipCheck agent, and is used to encrypt and decrypt communications between the MS and the agent. This procedure creates the RootCA and Source of Authority (SoA) certificates needed to encrypt and decrypt communication between the MS and the agent:

  1. Create a file $CERT/openssl.conf containing:
[ req ]
default_bits = 1024
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
countryName = Country Name (two letters long, e.g. US)
organizationName = Organization Name (e.g. ABC Inc.)
organizationalUnitName = Organizational Unit Name (e.g. Sales)
commonName = Common Name (e.g. rootca)
  1. Create the Root Certificate and private key. This certificate is self-signed and trusted throughout the Public Key Infrastructure (PKI) and Privilege management Infrastructure (PMI).
    The following command will require entering a password and verifying it. You will also be asked to enter the information that will be incorporated in the certificate.
# openssl req -config $CERT/openssl.conf \
-out $CERT/rootca.pem -keyout $CERT/rootcakey.pem \
-new -x509 -days 1000
Generating a 1024 bit RSA private key
.....++++++
.++++++
writing new private key to 'rootca.pem'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
 You are about to be asked to enter information that
will be incorporated
into your certificate request.
What you are about to enter is what is called a
Distinguished Name or a DN.
There are quite a few fields but you
can leave some blank.
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name :US
 Organization Name :ABC Inc.
 Organizational Unit Name :sales
 Common Name :rootca
The password you have to enter is used to encrypt the private key, so a third party cannot read it even if it is compromised. For this setup the password `changeit' is used. It is highly recommended to change this to your own secure password. It is also good practice to use different passwords to encrypt different keys.
  1. Most versions of openssl require a file containing a number, which is used to keep track of the current serial number of subsequent certificates that are being issued. We simply create this file using the following command: 
    # echo 000001 > $CERT/rootca.srl
    On a UW714 system only, also enter: 
    # cp $CERT/rootca.srl /.srl.
    The RootCA certificate we have created is used for authentication purposes and to ensure that certificates in our security setup have not been tampered with.
  2. The Privilege Management (authorization) component of our setup also requires a PMI user that acts as a root of trust, which is called the Source of Authority (SoA). This user needs a certificate and signing key to issue ACs. This certificate will be signed by the RootCA certificate to ensure its authenticity.
    The following command will require entering a password and verifying it. You will also be asked to enter the information that will be incorporated in the certificate. 
    # openssl req	-config $CERT/openssl.conf \

  -out $CERT/soareq.pem -keyout $CERT/soakey.pem -new
 
    Generating a 1024 bit RSA private key

    .........++++++

    ......................++++++

    writing new private key to 'soakey.pem'

    Enter PEM pass phrase:

    Verifying - Enter PEM pass phrase:

    -----

    You are about to be asked to enter information that

    will be incorporated

    into your certificate request.

    What you are about to enter is what is called a

    Distinguished Name or a DN.

    There are quite a few fields but you can leave some

    blank

    For some fields there will be a default value,

    If you enter '.', the field will be left blank.

    -----

    Country Name []:US

    Organization Name []:ABC Inc.

    Organizational Unit Name []:sales

    Common Name []:soa
    Create a certificate keystore by executing the following command:
# $KT -genkey -alias tomcat -keyalg RSA \
-keystore $CERT/tomcat.keystore
Specify a password value of "changeit".
  1. We now need to generate a certificate request using the public key we have just created, sign it with our `rootca' certificate, and import it into the keystore. We also have to import the rootca certificate itself as a trusted certificate, so that the chain of authorization can be established. 
    # $KT -certreq -keystore $CERT/tomcat.keystore \

    -storepass changeit -alias tomcat \

    -file $CERT tomcatreq.pem
 
# openssl x509		-in $CERT/tomcatreq.pem \

    -out $CERT/tomcat.pem -CA $CERT/rootca.pem \

    -CAkey $CERT/rootcakey.pem -days 365 -req
 
# $KT	-import -keystore $CERT/tomcat.keystore \

    -storepass changeit -alias rootca \

    -file $CERT/rootca.pem -trustcacerts
    Answer "yes" when asked to trust this certificate. 
    # $KT -import -keystore $CERT/tomcat.keystore \

    -storepass changeit -alias tomcat \

    -file $CERT/tomcat.pem
Installing the proxy

Installation instructions for the HipCheck Proxy Agent Relay are contained in the README file on the Download page at the HipCheck Portal. The Proxy Agent Relay is available for SCO UNIX systems only, and can be installed either on a system running a HipCheck agent or another system.

Configuring HipCheck to use the proxy

A Proxy Relay connection is defined when you add a new system to be monitored, or by modifying the attributes of an existing monitored system. See "Set up systems to be monitored" in Chapter 2, "Getting started".

Direct through https; default certificate

This connection type specifies an encrypted direct connection (no proxy) between the MS and the HipCheck agent. It uses self-signed certificates on both the client and server side to provide improved security.

To configure this connection type:

  1. Perform all of the steps listed in these two sections:
  2. Choose the Direct through https Agent Connection Type when creating a new system to be monitored, or changing the attributes of an existing system. See "Set up systems to be monitored" in Chapter 2, "Getting started".

Direct through https; user certificate

This connection type is not supported in this release of HipCheck.

Firewall Issues

The ports used by the HipCheck Mobility Server and the HipCheck agents must be opened on any firewall between the systems. By default, ports 8080 on SCO UNIX and port 8081 on Windows are used by agents for http; for https, port 8443 is used.

These defaults can be changed by stopping Tomcat, editing the line containing "port=" in the Tomcat configuration file (conf/server.xml) configuration on the agent system, and restarting Tomcat. On the Mobility Server side, specify the same port number in the "System URL" field on the "Create New System" or "Modify System Attributes" pages at the HipCheck Portal. See "Set up systems to be monitored" in Chapter 2, "Getting started".

Testing the MS to Agent Connection

To test the setup so far, Tomcat must be running. Check its status and, if necessary, start it using the following commands on SCO UNIX: 

# /etc/init.d/tomcat status

# /etc/init.d/tomcat start

On Windows, see the section "Checking status and troubleshooting problems".

Using a web browser, access the Tomcat server through `https://localhost:8443/axis' from the MS. It should ask you to accept the Tomcat certificate and then deny access. This is because the client authentication fails as we have not presented our own certificate. Most browsers support client authentication and allow you to add a pkcs12 format file in the security options. For instance, using the Firefox web browser, go to 

Tools>Preferences>Advanced>Security>View Certificates

and then add the httpd.p12 certificate. When we access the page again (you might have to restart the browser) it should now present you with the Axis web page, indicating that the client-side authentication and the encryption works properly.

TOC PREV NEXT