Hyrax - Administrators Interface
- 1 Overview
- 2 Installation & Configuration
- 3 Using the Hyrax Admin Interface
- 4 OLFS Log Viewer
- 5 BES Controls
2 Installation & Configuration
When Hyrax and Tomcat are installed all of the software needed to run the Hyrax Administrative Interface (HAI) is in place. However, you will need to do three simple steps in order to turn it in and use it. First you will need to configure Tomcat to use Secure Sockets Layer (SSL, https) and add a user who can login to use the interface. Then you will need to perform minimal additional configuration steps in the two parts of Hyrax - the BES and OLFS.
- Tomcat 6 installed and working, and
- Hyrax has been installed and simple responses work.
- It's very likely that newer versions of Tomcat will work and it's also likely that you can use another servlet engine, but the specifics of the SSL/https configuration may e different.
2.1 Configuring Tomcat
In order to use the HAI you will need to configure your tomcat instance to enable SSL. This is very simple for most sites, and it might already be configured for you. We use SSL/https for communication with the HAI because we want to be sure that your server is secure and only those people who you want to control it can. There is a much more detailed document that describes the SSL/https configuration for tomcat at the Apache web site.
- Make a Certificate 'keystore'
- Use the command "keytool -genkey -alias tomcat -keyalg RSA" to make a keystore - a place where SSL certificates are stored so they can be used by the server - and add a single self signed certificate in it. Make sure to remember the password for the keystore! If your installation of Tomcat is already configured for SSL, skip this step - you don't need to make the keystore or the self-signed certificate. Also note that if the keytool program cannot be run from a terminal, try using it's full path with is $JAVA_HOME/bin/keytool (Unix/OSX) or %JAVA_HOME%\bin\keytool (Windows).
- Turn on SSL/https
- In the file $CATALINA_BASE/conf/server.xml remove the comment surrounding the "SSL HTTP/1.1 Connector" entry. This is described in more detail in the Configuration section tomcat documentation.
- Add a Tomcat user
- Open the file $CATALINA_HOME/conf/tomcat-users.xml and add a user for the interface. Hyrax uses, by default, the role 'manager', so if you already have a user in that role an want them to use the HAI, you are all set. If you don't have anyone set in the manager role, or you want a new user, add a line like the following: <user username="admin" password="hai" roles="manager"/>. If you don't have the role 'manager' defined, add it too: <role rolename="manager"/>
- Restart Tomcat
Edit the file $HYRAX_HOME/etc/bes.conf and uncomment this line:
Restart the BES and you're ready.
The HAI is a regular part of the OLFS distribution and simply needs to be enabled by configuring the OLFS to communicate with the BES admin port, and by configuring Tomcat to allow you to access the UI.
In the file $CATALINA_HOME/content/opendap/olfs.xml remove the comments around the line <adminPort>11002</adminPort>
2.3.2 Tomcat Users
You will need to configure Tomcat to support container-managed security, by connecting to an existing "database" (aka Realm) of usernames, passwords, and user roles. Tomcat supports several authentication Realms including LDAP. What follows are simple instructions for getting a Memory-Realm working. The Memory-Realm is not for production use, and the example is provided only as a means by which to easily demonstrate and allow one to test the HAI features.
- Edit the file
- Add a user whose role is "manager":
<user username="admin" password="foo" roles="manager" />
And be sure to make the password something better than "foo".
2.4 Configuration notes
- Note that because the HAI is a web-based interface, with secure logins using SSL, you can use the interface with your server from anywhere in the world. It might be a good idea, however, to limit the IP addresses that can access the HAI.
- Using a self-signed certificate is fine, but you will see a warning box when you log in because self-signed certs are not trusted by browsers by default. Most browsers have an option that will suppress that warning or, although it involves some expense, you can get a certificate signed by a Certificate Authority and install that in the keystore
2.4.1 Olfs Details
The HAI servlet (as part of the Hyrax web application) utilizes a <security-constraint> element, and a <login-config> element that defines how administrators are required to authenticate themselves.
In the case of the HAI we use BASIC authentication over an SSL channel. The <transport-guarantee> ensures that the url's defined <web-resource-collection> can only be accessed via a secure channel:
<security-constraint> <web-resource-collection> <web-resource-name>Hyrax Admin Interface</web-resource-name> <url-pattern>/hai/*</url-pattern> <url-pattern>/docs/admin/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>manager</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>
3 Using the Hyrax Admin Interface
Note: We often refer to the interface as either the HAI or just the interface.
To access the the interface, use the following URLs:
You will need to login using a user who is assigned the manager role as described above.
Once logged in, you will see a page with several links. Each one takes you to a different part of the interface so you can easily open them as tabs or separate windows in you browser.
Note that because the HAI is a web-based interface, with secure logins using SSL, you can use the interface with your server from anywhere in the world. It might be a godd idea, however, to limit the IP addresses that can access the HAI.
In order to understand this tool it may be helpful to review how Hyrax is structured: Hyrax is composed of one OLFS and one or more BES process. These are not required to be running on the same system.
4 OLFS Log Viewer
The OLFS Log Viewer controller is located at: https://test.opendap.org:8453/opendap/docs/admin/olfsLogView.jsp
The default page looks like this:
4.1 Log Viewer Controls
4.2 Setting logging levels
5 BES Controls
The BES controller is located at: https://test.opendap.org:8453/opendap/docs/admin/besctl.jsp
The default page looks like this:
Beneath the "BES Management " banner you will see one or more tabs. You will always see a tab with the title of "/". This is the default BES for this Hyrax. If the particular installation of Hyrax has multiple BES configured in its OLFS they will appear here as tabs where the "prefix" for the BES from the olfs.xml file will be used as the tab title.