From IcedTea

Contents 1 RHSCL 2.3 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.6

1 RHSCL 2.3 Thermostat User Guide

If you have obtained Thermostat from the Red Hat Software Collections version 2.3 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 rh-thermostat16

1.2 Installation Locations

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

THERMOSTAT_HOME 

/opt/rh/rh-thermostat-16/root/usr/share/thermostat

USER_THERMOSTAT_HOME 

~/.thermostat-1.6

1.3 Enabling Thermostat

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

$ scl enable rh-thermostat16 bash

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

$ thermostat --version
Thermostat version 1.6.4

Next try to print the help message:

$ thermostat help

It will print help output similar to the following:

list of commands:

 help                   show help for a given command or help overview
 agent                  run the thermostat agent
 agent-info             show info for an agent
 clean-data             drop all data related to all of the specified agents
 dump-heap              trigger a heap dump on the VM
 find-objects           find objects in a heapdump
 find-root              find the shortest path from an object to a GC root
 gc                     perform Garbage Collection on the given vm
 gui                    launch the GUI client
 kill-vm                kill the specified vm
 list-agents            list all agents
 list-heap-dumps        list all heap dumps
 list-vms               list all known VMs
 object-info            show information about an object in a heap dump
 ping                   send a ping to a running agent
 profile-vm             instrument and profile a target vm
 save-heap-dump-to-file save a heap dump to a local file
 service                run the thermostat storage and agent
 setup                  setup thermostat for first run
 shell                  launch the Thermostat interactive shell
 show-gc-name           show the configured garbage collector name of a given VM
 show-heap-histogram    show the heap histogram
 storage                control or view the status of the thermostat storage
 storage-profile        profile how fast storage operations are
 validate               validate a thermostat plug-in XML file
 vm-info                show basic information about a VM
 vm-stat                show various statistics about a VM
 web-storage-service    start mongodb storage, an embedded servlet container and an agent

There is also a man page available:

 $ man thermostat

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.

$ thermostat setup

Thermostat will guide you through the required configuration. Please take note of the Thermostat client and Thermostat agent credentials.

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 - which it should not do if setup worked properly and stored credentials in the keyring -, use the "Thermostat client" credentials you've configured via thermostat setup above.

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

 $ thermostat gui

That's it!

With Thermostat 1.6 and better bash/shell completions are available as well. Typing something like:

 $ thermostat li<TAB>

should complete to:

 $ thermostat list-

Hitting <TAB> twice once again will show available completions for commands starting with list- like so:

 $ thermostat list-
 list-agents      list-heap-dumps  list-vms

The same works in thermostat shell, but there it also completes some useful options such as vmId or agentId.

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.3 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 rh-thermostat16-thermostat-tomcat start

For RHEL 7.1 and later:

# service tomcat@rh-thermostat16 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/rh-thermostat16/root/etc/thermostat/web.auth
/opt/rh/rh-thermostat16/root/etc/thermostat/thermostat-users.properties
/opt/rh/rh-thermostat16/root/etc/thermostat/thermostat-roles.properties

1.7 Data/Plugin Migration from Thermostat < 1.6

Please note that a data migration path from Thermostat < 1.6 to 1.6 is not supported.

However, if you are planning on upgrading to Thermostat 1.6 as part of Red Hat Software Collections version 2.3 and you want to retain data from Thermostat 1.x.y we recommend to dump data from the thermostat MongoDB database via mongodump and restore it via mongorestore. Additionally, any user-installed plugins may not be visible in Thermostat 1.6. The reason for this is because USER_THERMOSTAT_HOME for 1.6 is defined to be ~/.thermostat-1.6. In order to migrate plugins, please copy/move folder ~/.thermostat{,1.4}/data/plugins to ~/.thermostat-1.6/data/plugins.