Thermostat/DevDeployWarInTomcatNotes

From IcedTea

Jump to: navigation, search

Thermostat Home

Contents

1 Test Setup for Tomcat-Deployed Web Storage

In this document we describe how the web layer can be deployed and used in tomcat for development purposes.

1.1 Preliminary Setup

  1. Download a binary distribution of Apache Tomcat core (version 7 and up should do)
  2. Extract the tar file in your home directory somewhere. We'll call the folder containing tomcat henceforth as $CATALINA_HOME

1.2 Enable SSL in Tomcat (optional)

Edit $CATALINA_HOME/conf/server.xml so that a https connector gets started:

<Connector port="8443" maxThreads="200"
          scheme="https" secure="true" SSLEnabled="true"
          keystoreFile="${user.home}/tomcat.keystore" keystorePass="keystorePassword"
          protocol="org.apache.coyote.http11.Http11NioProtocol"
          clientAuth="false" sslProtocol="TLS"/>

Steps below describe how you can convert a self-signed cert and private key which was generated via openssl to a Java compatible JKS keystore. File tomcat.keystore above.

$ openssl pkcs12 -export -in server.crt -inkey server.key -out keystore.pkcs12

server.crt is a self-signed certificate. server.key is the private key of the tomcat server.

$ keytool -importkeystore -srckeystore keystore.pkcs12 -destkeystore server.keystore -srcstoretype pkcs12

This produces a server.keystore file which can be copied to /usr/share/tomcat/tomcat.keystore in order to use that for serving https requests via tomcat.

1.3 Build Thermostat From Source and Deploy the Thermostat Webapp

$ hg clone http://icedtea.classpath.org/hg/thermostat
$ cd thermostat
$ mvn -Dthermostat.web.deploy.dir=$CATALINA_HOME/webapps/thermostat clean integration-test                         # Builds thermostat from source, copies thermostat webapp to $CATALINA_HOME/webapps/thermostat
$ export JAVA_OPTS="-Djava.security.auth.login.config=$(pwd)/distribution/target/image/etc/thermostat_jaas.conf"   # Set JAAS login module config via JAVA_OPTS (required to be set prior tomcat startup)
$ ./distribution/target/image/bin/thermostat storage --start                                                       # Starts thermostat storage (mongodb backend)
$ $CATALINA_HOME/bin/startup.sh                                                                                    # Starts tomcat, deploys thermostat webapp in $CATALINA_HOME/webapps/thermostat

Once that is done the storage URL is:

http://127.0.0.1:8080/thermostat/storage

Or if using SSL:

https://127.0.0.1:8443/thermostat/storage

This URL can be used to connect the thermostat agent/client/shell respectively. Note that with this setup authentication and authorization will be performed, so appropriate user setup in $THERMOSTAT_HOME/etc/thermostat-users.properties and $THERMOSTAT_HOME/etc/thermostat-roles.properties will be required.

There are several files, where some modifications may be needed (the meaning of $THERMOSTAT_HOME can be the directory thermostat/distribution/target/image, where thermostat executables are palced in directory bin and the configuration files are in directory etc, and meaning of $USER_THERMOSTAT_HOME can be e.g. ~/.thermostat - this is the directory, where the configuration, data, ... things that change more often are stored). The default versions of these files are all in $THERMOSTAT_HOME/etc, you may need to copy them into $USER_THERMOSTAT_HOME/etc :

1.3.1 $USER_THERMOSTAT_HOME/etc/agent.properties

regarding the web storage the last part of this file is relevant, because it gives the connection url to the storage. The value is by default mongodb://127.0.0.1:27518 and for web storage it is http://127.0.0.1:8080/thermostat/storage (lines can be commented/uncommented with #).

# Connection URL to storage. This can be overridden with the -d option
# on the command line. In order to use web storage instead, use something
# similar to the following line:
#DB_URL=https://storage-server.example.com:8443/thermostat/storage
#DB_URL=mongodb://127.0.0.1:27518
DB_URL=http://127.0.0.1:8080/thermostat/storage

1.3.2 $USER_THERMOSTAT_HOME/etc/agent.auth

login and password that will be used by agent when connecting to the storage (be it mongodb or web storage) are in this file. When there is nothing, the agent supposes it can connect without login, for mongodb this is ok by default, for web storage the login is needed. On the other hand, if login is given agent uses it for any connection to the storage, so it may not be able to connect to mongodb if mongodb does not have such user+password configured. Example of whole agent.auth file:

# This file is intended to be read by a hand-rolled reader/parser, to avoid
# passwords needing to be represented as String objects at runtime.  It must
# be saved with Unix line end characters, and encoded as ascii.
# Uncomment the following lines and replace with your storage authentication
# parameters as needed.
#
username=agent-tester
password=securepassword1

1.3.3 $USER_THERMOSTAT_HOME/etc/client.properties

this is exactly the file that can be changed every time you open the "Edit client preferences" dialog in gui and set connection details of the clients connection to the storage. Example of a whole file:

#
#Thu Aug 22 16:10:25 CEST 2013
password=supersecurepassword2
connection-url=http\://127.0.0.1\:8080/thermostat/storage
save-entitlements=true
username=client-tester

1.3.4 $THERMOSTAT_HOME/etc/thermostat-users.properties

the list of thermostat users and their passwords, example of lines that can be added at the end to introduce 2 users:

agent-tester=securepassword1
client-tester=supersecurepassword2

1.3.5 $THERMOSTAT_HOME/etc/thermostat-roles.properties

the roles that can be assigned to thermostat users, described in the commented first part of this file, the last few lines that you may want to add are:

agent-tester=thermostat-agent
client-tester=thermostat-client
thermostat-agent=thermostat-write, \
                 thermostat-save-file, \
                 thermostat-purge, \
                 thermostat-prepare-statement, \
                 thermostat-register-category, \
                 thermostat-cmdc-verify, \
                 thermostat-login, \
                 thermostat-realm
# Grants users who are member of the "thermostat-client" role ALL read privileges.
# See http://icedtea.classpath.org/wiki/?title=Thermostat/SecurityConsiderations#Thermostat_Access_Control
thermostat-client=thermostat-agents-grant-read-agentId-ALL, \
                  thermostat-hosts-grant-read-hostname-ALL, \
                  thermostat-vms-grant-read-vmId-ALL, \
                  thermostat-vms-grant-read-username-ALL, \
                  thermostat-realm, \
                  thermostat-login, \
                  thermostat-query, \
                  thermostat-prepare-statement, \
                  thermostat-cmdc-generate, \
                  thermostat-load-file, \
                  thermostat-register-category

1.4 Thermostat Keystore Setup

Above we assumed that tomcat serves https request with a self-signed certificate. In order to tell thermostat to trust certificates signed by your own certificate authority one has two options:

  1. Import the certificate of your custom CA into ${java.home}/lib/security/cacerts
  2. Create a custom key store which has the certificate of your custom CA imported and thermostat knows where to find this keystore

For 1. the import command would be something like this (no extra Thermostat config required):

$ keytool -import -trustcacerts -alias root -file ca.crt -keystore ${java.home}/lib/security/cacerts

This would import the certificate of your CA (ca.crt) into keystore ${java.home}/lib/security/cacerts

For 2. one could use the following commands to create the keystore and import the ca.crt

$ keytool -genkey -alias com.redhat.thermostat -keyalg RSA -keystore thermostat.keystore
$ keytool -import -trustcacerts -alias root -file ca.crt -keystore thermostat.keystore

This would leave you with a file called thermostat.keystore which you can now tell thermostat about via the config file $THERMOSTAT_HOME/etc/ssl.properties. Set KEYSTORE_FILE to the path of "thermostat.keystore" above and KEYSTORE_PASSWORD to the password which you've used for the keystore while generating it.

1.5 Generate Self Signed Server Certificate with OpenSSL

$ openssl genrsa -out ca.key 4096

ca.key => private key of "our" certificate authority

$ openssl req -new -x509 -days 1826 -key ca.key -out ca.crt

ca.crt => certificate of "our" certificate authority (valid for 5 years)

$ openssl genrsa -out server.key 4096

server.key => private key of the server which serves signed cert

$ openssl req -new -key server.key -out server.csr

server.csr => certificate signing request of server's certificate

$ openssl x509 -req -days 730 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt

server.crt => certificate signed by ca.crt via server.csr (valid for 2 years)

1.6 Generate all needed files (development only)

The following Makefile generates all the required certificates and keystores needed.

KEYTOOL=keytool
OPENSSL=openssl

all: ca.key ca.crt server.key server.csr server.crt thermostat.keystore server.keystore

ca.key:
    $(OPENSSL) genrsa -out $@ 4096

ca.crt: ca.key
    $(OPENSSL) req -new -x509 -days 1826 -key $< -out $@

server.key:
    $(OPENSSL) genrsa -out $@ 4096

server.csr: server.key
    $(OPENSSL) req -new -key $< -out $@

server.crt: server.csr ca.crt ca.key
    $(OPENSSL) x509 -req -days 730 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out $@
thermostat.keystore: ca.crt
    $(KEYTOOL) -genkey -alias com.redhat.thermostat -keyalg RSA -keystore $@
    $(KEYTOOL) -import -trustcacerts -alias root -file $< -keystore $@

keystore.pkcs12: server.crt server.key
    $(OPENSSL) pkcs12 -export -in server.crt -inkey server.key -out $@

server.keystore: keystore.pkcs12
    $(KEYTOOL) -importkeystore -srckeystore $< -destkeystore $@ -srcstoretype pkcs12

clean:
    rm -f ca.key
    rm -f ca.crt
    rm -f server.key
    rm -f server.csr
    rm -f server.crt
    rm -f thermostat.keystore
    rm -f keystore.pkcs12
    rm -f server.keystore
Personal tools