Thermostat/UserGuide
From IcedTea
Contents |
Thermostat User Guide
NOTE: This page is a draft and my change frequently
Overview
It is important to know that Thermostat consists of three (3) main components: agent, storage and client (in whatever form). The most important part is storage. Without storage the agent and the built-in client will refuse to start. After all the information needs to be stored somewhere :)
Local Thermostat Setup
Storage
The storage layer of Thermostat can be started as follows. In the default configuration, this will start a mongo DB server on localhost:
$ ./bin/thermostat storage --start Jul 31, 2012 10:45:00 AM com.redhat.thermostat.service.activator.Activator start INFO: activating thermostat-process bundles starting storage server... server listening on ip: mongodb://127.0.0.1:27518
Similarly, storage can be stopped as follows:
$ ./bin/thermostat storage --stop Jul 31, 2012 11:08:50 AM com.redhat.thermostat.service.activator.Activator start INFO: activating thermostat-process bundles server shutdown complete: /path/to/thermostat/storage/db log file is here: /path/to/thermostat/storage/logs/db.log
Agent
After the storage layer is up and running, the agent, or data collector, can be started as follows (note that the argument to the -d option should match whatever the output of the storage command was):
$ ./bin/thermostat agent -d mongodb://127.0.0.1:27518 Jul 31, 2012 11:12:46 AM com.redhat.thermostat.service.activator.Activator start INFO: activating thermostat-process bundles Agent id: 7a832af6-9677-481a-955c-c6b9d59d9296 agent started.
The agent can be stopped by pressing CTRL+C on the terminal where the agent was started.
Swing Client
The built-in Swing GUI client can be started via:
$ ./bin/thermostat gui
There is also a built-in shell which can be started as follows:
$ ./bin/thermostat shell
Service
Thermostat provides an additional command, "service", which is a short-cut for starting the storage and agent directly. Although it is considered an internal option, it was decided to leave it available for now since, even if it doesn't offer the flexibility and the number of options of the other commands, it is still very useful to quickly run Thermostat:
$ ./bin/thermostat service
Remote Thermostat Setup
Note: If you want to use Thermostat in a remote setup it is strongly advised to have a look at our Thermostat security considerations page.
In this example setup we assume that storage runs on host A, the thermostat agent runs on host B and the thermostat client runs on host A. Let's assume host A has IP 192.168.0.1 and host B 192.168.0.2 respectively.
Storage
In order to be able to use Thermostat in a distributed environment, storage needs to be configured to bind to a proper IP address of the host on which storage is running on. Moreover autnentication needs to be properly set up for it to work. Here is how this can be done.
Add admin user in mongo and add a user to the thermostat db:
$ ./bin/thermostat storage --start
$ mongo 127.0.0.1:27518
MongoDB shell version: 2.0.6
connecting to: 127.0.0.1:27518/test
> use admin
switched to db admin
> db.addUser("adminUser", "adminPassword")
{ "n" : 0, "connectionId" : 3, "err" : null, "ok" : 1 }
{
user" : "adminUser",
"readOnly" : false,
"pwd" : "b9453af5a2b4eb85e098a70c2fbf38b4",
"_id" : ObjectId("504f019876aefbdbe7b34983")
}
> db.auth("adminUser", "adminPassword")
1
> use thermostat
switched to db thermostat
> db.addUser("thermostat", "thermostat")
> exit
bye
$ ./bin/thermostat storage --stop
Next, we configure storage settings to bind to our host's IP address. In order to do so change the BIND parameter in $THERMOSTAT_HOME/storage/db.properties (e.g. ./distribution/target/storage/db.properties). Similarly, the port which is used for storage can be configured that way. In our example, we change the BIND parameter to: BIND=192.168.0.1 and leave the rest as is.
Finally, on host A, we execute:
$ ./bin/thermostat storage --start Launching... Sep 11, 2012 11:44:08 AM com.redhat.thermostat.service.activator.Activator start INFO: activating thermostat-process bundles Sep 11, 2012 11:44:09 AM com.redhat.thermostat.agent.command.internal.Activator start INFO: activating thermostat-agent-confserver starting storage server... server listening on ip: mongodb://192.168.0.1:27518 log file is here: path/to/thermostat/storage/logs/db.log pid: 4929
Agent
Next, we need to configure the binding address of the agent. The binding address of the agent is required to be set in order to enable the command-channel (i.e. let client and agent talk directly). In order to do so, modify $THERMOSTAT_HOME/agent/agent.properties and set CONFIG_LISTEN_ADDRESS to 192.168.0.2:12000. After that we can start the agent on host B which connects to storage on host A.
$ ./bin/thermostat agent -d mongodb://192.168.0.1:27518 --username thermostat --password thermostat Launching... Sep 11, 2012 11:56:12 AM com.redhat.thermostat.service.activator.Activator start INFO: activating thermostat-process bundles Sep 11, 2012 11:56:12 AM com.redhat.thermostat.agent.command.internal.Activator start INFO: activating thermostat-agent-confserver Sep 11, 2012 11:56:12 AM java.util.prefs.FileSystemPreferences$6 run WARNING: Prefs file removed in background ~/.java/.userPrefs/thermostat/prefs.xml Agent id: eb8bc50f-7433-4ce6-ba1d-fa877165315a agent started.
Swing Client
We can now fire up the swing client on host A:
$ ./bin/thermostat gui
This will report that it cannot connect to storage and provides a configuration dialog for setting it up. Click on "Configure" to do so:
In the configuration dialog enter the correct IP and username/password of the storage on host A (make sure to check "Save entitlements"):
Press "OK" and you should see the familiar thermostat swing UI with information collected on host B.
Shell Client
Alternatively, the interactive shell can be used in a remote setup as well. Here are a few examples (assuming 1.2.4.5 is the IP of host A):
$ ./bin/thermostat shell Thermostat > list-vms Could not connect to: mongodb://1.2.4.5:27518 Thermostat > connect -d mongodb://1.2.4.5:27518 -u youruser -p yourpassword Thermostat > list-vms HOST_ID HOST VM_ID STATUS VM_NAME 44b67f40-e89e-4fbe-bf72-845a4074f81e remoty.example.com 1716 RUNNING com.redhat.thermostat.main.Thermostat
Piece of cake ;-)
Web Service
Thermostat can be used over http(s):// storage URLs. This is the only secure option of using Thermostat remotely. Thermostat's Web Storage layer can be thought of as a thin abstraction on top of a backing storage implementation (currently mongodb). It adds certain security features such as authentication and authorization as well as TLS support. Note that for this to work correctly a few things need to be properly configured.
Steps are (roughly) as follows:
- ./bin/thermostat storage --start
- Deploy the thermostat web war in your favourite servlet container, configure a https connector and set up some basic roles. See our tomcat development testing page for hints.
- ./bin/thermostat agent -d https://yourhost.example.com/servlet-context-thermostat/storage --username thermostat --password thermostat
- ./bin/thermostat gui (make sure that https:// storage URL is used in client preferences)
