From IcedTea

Contents 1 RHSCL 2.0 Thermostat User Guide 1.1 Installation 1.2 Installation Locations 1.3 Enabling Thermostat 1.4 First Time Configuration 1.5 Using Thermostat 1.6 System-wide Web Storage Endpoint 1.7 Data/Plugin Migration from Thermostat 1.0.4 (RHSCL 1.2)

1 RHSCL 2.0 Thermostat User Guide

If you have obtained Thermostat from the Red Hat Software Collections version 2.0 release here are a few things you should be aware of.

1.1 Installation

You can install Thermostat via the following command (provided you've enabled appropriate channels):

# yum install thermostat1

1.2 Installation Locations

Thermostat as part of Red Hat Software Collections version 2.0 installs into /opt/rh. More specifically the common THERMOSTAT_HOME and USER_THERMOSTAT_HOME have different values from upstream:

THERMOSTAT_HOME 

/opt/rh/thermostat1/root/usr/share/thermostat

USER_THERMOSTAT_HOME 

~/.thermostat-1.2

1.3 Enabling Thermostat

In order to make thermostat commands available in Red Hat Software Collections 2.0 perform the following command:

$ scl enable thermostat1 bash

After this, the following command should print the Thermostat version (1.2.x):

$ thermostat --version
Thermostat version 1.2.0

Next try to print the help message:

$ thermostat help

If everything is set up correctly, it will print help output similar to the following:

list of commands:
 
 help                   show help for a given command or help overview
 agent                  starts and stops the thermostat agent
 agent-info             shows info for specified agent
 clean-data             drop all data related to all of the specified agents
 dump-heap              trigger a heap dump on the VM
 find-objects           finds objects in a heapdump
 find-root              finds the shortest path from an object to a GC root
 gc                     perform Garbage Collection on the given vm
 gui                    launches the GUI client
 kill-vm                kill the specified vm
 list-agents            lists all agents for the current host
 list-heap-dumps        list all heap dumps
 list-vms               lists all currently monitored VMs
 object-info            prints information about an object in a heap dump
 ping                   using the Command Channel, send a ping to a running agent
 profile-vm             profile a target vm
 save-heap-dump-to-file saves a heap dump to a local file
 service                starts and stops the thermostat storage and agent
 shell                  launches the Thermostat interactive shell
 show-heap-histogram    show the heap histogram
 storage                starts and stops the thermostat storage
 storage-profile        profile how fast storage operations are
 validate               validates a thermostat plug-in XML file against the schema
 vm-info                shows basic information about a VM
 vm-stat                show various statistics about a VM
 web-storage-service    starts mongodb storage, an embedded servlet container with the web archive deployed and then connects an agent to this web endpoint

Thermostat needs to be configured the first time it's executed, in this case the program will exit with the following message:

 $ thermostat help
 This appears to be the first time Thermostat has been launched.
 Please run 'thermostat-setup'.

1.4 First Time Configuration

Here's a simple configuration to get started. This makes thermostat work for a single local user only. Please see the complete User Guide for all details and other supported configurations.

First, we create a database user. This user is all powerful and can do anything:

1.

 $ echo -e 'yes\nmongodevuser\nmongodevpassword\nmongodevpassword' | thermostat-setup 

The script will complain about not being able to edit the system web.auth file. The next step will set values in the current user's web.auth file, since if the system web.auth file does not exist or is not readable the web storage endpoint will attempt to use the web.auth file in the user's home directory. That step - in turn - will configure the web storage endpoint to use username and password we have set up above to be able to connect to the backing database:

2.

 $ echo -e 'storage.username=mongodevuser\nstorage.password=mongodevpassword' > ~/.thermostat-1.2/etc/web.auth

Next, we set a username and password for the agent. Those are the credentials that the agent will use to validate against the web storage endpoint:

3.

 $ echo -e 'username=agent-tester\npassword=tester\n' > ~/.thermostat-1.2/etc/agent.auth

Next, we configure the web server to recognize two users. One for the agent and one for the client:

4.

 $ echo -e 'agent-tester=tester\nclient-tester=tester\n' > ~/.thermostat-1.2/etc/thermostat-users.properties

Finally, we configure the web server to give some limited powers to the agent and client users:

5.

 $ cat > ~/.thermostat-1.2/etc/thermostat-roles.properties <<EOF
    agent-tester = thermostat-agent
    client-tester = thermostat-client, thermostat-cmdc, thermostat-purge
    
    thermostat-agent = thermostat-cmdc-verify, \\
                       thermostat-login, \\
                       thermostat-prepare-statement, \\
                       thermostat-purge, \\
                       thermostat-register-category, \\
                       thermostat-realm, \\
                       thermostat-save-file, \\
                       thermostat-write, \\
                       thermostat-files-grant-write-filename-ALL
    
    thermostat-client = thermostat-agents-grant-read-agentId-ALL, \\
                        thermostat-cmdc-generate, \\
                        thermostat-hosts-grant-read-hostname-ALL, \\
                        thermostat-load-file, \\
                        thermostat-login, \\
                        thermostat-prepare-statement, \\
                        thermostat-query, \\
                        thermostat-realm, \\
                        thermostat-register-category, \\
                        thermostat-vms-grant-read-username-ALL, \\
                        thermostat-vms-grant-read-vmId-ALL, \\
                        thermostat-files-grant-read-filename-ALL, \\
                        thermostat-write
    
    thermostat-cmdc = thermostat-cmdc-grant-garbage-collect, \\
                      thermostat-cmdc-grant-dump-heap, \\
                      thermostat-cmdc-grant-thread-harvester, \\
                      thermostat-cmdc-grant-killvm, \\
                      thermostat-cmdc-grant-ping, \\
                      thermostat-cmdc-grant-jmx-toggle-notifications, \\
                      thermostat-cmdc-grant-profile-vm
EOF

1.5 Using Thermostat

First, please get a thermostat enabled bash shell (see the enablement section) and configure it (see the first time configuration section. After that one should be able to use thermostat as described in our general User Guide. To summarize:

First, start the web server:

 $ thermostat web-storage-service

Now you can use the client:

 $ thermostat list-vms

When it asks for a username and password, use:

• username: client-tester
• password: tester

This is the username/password you configured in the previous section.

You can also use the GUI. Use the same username/password as the list-vms command above:

 $ thermostat gui

That's it!

1.6 System-wide Web Storage Endpoint

For a use case where multiple, possibly remote, users use Thermostat (see the User Guide for details), there is a system service available in RHSCL 2.0 for deploying the web storage endpoint via system tomcat. You don't need this if all you want to do is run Thermostat as a single user. On the client machines where a Thermostat agent or Thermostat client runs you will need to configure Thermostat (see the configuration section) first. On the machine which hosts the shared web storage endpoint you will need to start the backing database yourself first and then deploy the web storage endpoint via the system service.

For RHEL 6 and 7.0:

# service thermostat1-thermostat-tomcat start

For RHEL 7.1 and later:

# service tomcat@thermostat start

This will start a local tomcat process with the thermostat web application deployed. That is, Thermostat agent and client can use the following URL for storage connections after starting this service:

http://127.0.0.1:8080/thermostat/storage

Before one exposes this storage URL outside of the local host, it is highly recommended to SSL-enable this tomcat instance. That can be done via standard Tomcat means. Note: The system service for deploying the web storage endpoint will use the tomcat package coming from base RHEL. Relevant configuration files for the system service are:

/opt/rh/thermostat1/root/etc/thermostat/web.auth
/opt/rh/thermostat1/root/etc/thermostat/thermostat-users.properties
/opt/rh/thermostat1/root/etc/thermostat/thermostat-roles.properties

1.7 Data/Plugin Migration from Thermostat 1.0.4 (RHSCL 1.2)

Please note that a data migration path from 1.0.4 Thermostat to 1.2 Thermostat is not supported.

However, if you are planning on upgrading to Thermostat 1.2 as part of Red Hat Software Collections version 2.0 and you want to retain data from Thermostat 1.0.4 we recommend to dump data from the thermostat MongoDB database via mongodump from the mongodb24 collection and restore it via mongorestore from the rh-mongodb26 collection. Additionally, any user-installed plugins may not be visible in Thermostat 1.2. The reason for this is because USER_THERMOSTAT_HOME changed location from ~/.thermostat to ~/.thermostat-1.2. In order to migrate plugins, please copy/move folder ~/.thermostat/data/plugins to ~/.thermostat-1.2/data/plugins.