Difference between revisions of "Hyrax - Administrators Interface"

From OPeNDAP Documentation
m (Installation & Configuration)
 
(26 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
  
 +
The Hyrax Administrator's Interface (HAI) is a graphical interface to the configuration files and run-time logs of the Hyrax data server. It provides a way to start and stop different parts of Hyrax and to change their configuration files on the fly. Because Hyrax can run on several different hosts, it can be a challenge to manage; the HAI provides a single tabbed interface where the logs and configuration files for those different hosts can easily be tracked.
 +
 +
The HAI is a web based interface, so it can be used from any computer that can access the server using a secure connection.
 +
 +
The following describes the installation and configuration of the HAI followed by an explanation of its features. Note that the interface is very simple to configure in most cases - most of the steps described for Tomcat are not necessary for many sites since it's often the case that the servlet engine is already configured for SSL and has one or more users in Tomcat's ''manager'' role. Using the interface is very intuitive.
  
 
== Installation & Configuration ==
 
== 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. Be sure to skim the Configuration Notes subsection.
 +
 +
Prerequisites:
 +
* 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 be different.
 +
 +
=== 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 [http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html SSL/https configuration] for tomcat 7 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. For Tomcat 7, add attributes for the keystore and keystore password (e.g., ''keystoreFile="${user.home}/.keystore" keystorePass="changeit"'') to SSL HTTP/1.1 Connector entry.
 +
;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
  
 
=== BES ===
 
=== BES ===
  
The HAI is a regular part of the BES it is not a module that needs to be added. It just needs to be enabled by editing the BES configuration file and restarting the BES.
+
Edit the file ''$HYRAX_HOME/etc/bes.conf'' and remove the comments from the line ''BES.DaemonPort=11002''
 +
 
 +
Restart the BES.
 +
 
 +
=== OLFS ===
  
===== how-to =====
+
Edit the file ''$CATALINA_HOME/content/opendap/olfs.xml''  and remove the comments around the line ''<adminPort>11002</adminPort>''
  
Edit the file <code>$HYRAX_HOME/etc/bes.conf</code> and uncomment this line:
+
=== Configuration notes ===
  
BES.DaemonPort=11002
+
# 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
 +
# More about tomcat users: Tomcat supports several authentication Realms including Memory realms, databases and LDAP. We document using memory realms here because other techniques, while better in some ways, are more cumbersome. If you are using memory realms, be sure to protect the ''tomcat-users.xml'' file because it contains plain text passwords.
 +
# The ''<security-constraint>'' element in the ''$CATALINA_HOME/opendap/WEB-INF/web.xml'' configuration file controls the level of access control for the HAI
 +
# The role used by the HAI is set in the ''$CATALINA_HOME/opendap/WEB-INF/web.xml'' configuration file using the ''<auth-constraint>'' element. You can switch roles by changing the ''<role-name>''.
  
Restart the BES and you're ready.
+
== Using the Hyrax Administrator's Interface ==
  
 +
To access the Hyrax Administrator's Interface, go to the base page for your server (http://''you server''/opendap) and follow the link to the ''Hyrax Admin Interface''. Following that link will present a page where you login to the interface proper. Use the username and password for a user assigned to the ''manager'' role for your Tomcat server (see the configuration information above for more information about Tomcat users and roles).
 +
<!--
 +
Note: We often refer to the interface as either the ''HAI'' or just ''the interface''.
 +
 +
To access the the interface, use the following URLs:
 +
* <code><nowiki>https://test.opendap.org:8443/opendap/docs/admin/index.jsp</nowiki></code> or <code><nowiki>https://test.opendap.org:8443/opendap/docs/admin/</nowiki></code>
 +
* <code><nowiki>http://test.opendap.org:8080/opendap/docs/admin</nowiki></code>
 +
 +
You will need to login using a user who is assigned the ''manager'' role as described above.
 +
-->
 +
Once logged in to the HAI, you will see a page with two main links; one for the Hyrax front-end and one link for the back-end servers. Together the front-end and the back-end servers make up one installation of Hyrax and they can be spread across several machines. Generally the front-end is run on a host that is outside your institution's firewall, while the back-end servers are inside that firewall on hosts where data are located. It may be helpful to review how [http://docs.opendap.org/index.php/Hyrax#Overview Hyrax] is structured: Hyrax is composed of one [http://docs.opendap.org/index.php/Hyrax_-_OLFS_Configuration front-end server (OLFS)] and one or more [http://docs.opendap.org/index.php/Hyrax_-_BES_Configuration back-end server (BES)] process.
 +
 +
Since there is just one instance of the front-end, it has a fairly simple control panel. The back-end servers' control panel is a little more complex because there can be many different back-end servers all part of one Hyrax installation. Use the tabs at the top of the interface to select different back-end server instances. The following sections describe both parts of the interface.
 +
<!--
 +
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.
  
=== OLFS ===
 
  
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 order to understand this tool it may be helpful to review how [http://docs.opendap.org/index.php/Hyrax#Overview Hyrax] is structured: Hyrax is composed of one [http://docs.opendap.org/index.php/Hyrax_-_OLFS_Configuration OLFS] and one or more [http://docs.opendap.org/index.php/Hyrax_-_BES_Configuration BES] process. These are not required to be running on the same system.
 +
-->
 +
=== OLFS Log Viewer ===
 +
<!-- The OLFS Log Viewer controller is located at: https://test.opendap.org:8453/opendap/docs/admin/olfsLogView.jsp -->
 +
The OLFS control panel provides access to the log for the front-end of Hyrax. Note that the control panel provides a way to set the logging level for individual classes that make up the front end of the server; this is very useful for debugging and testing new front-end plugins but it rarely needed in an operation setting. The default logging level shipped with the server is generally the most useful level of detail. By default the log lines are not displayed - just click the start button to see them.
  
==== olfs.xml ====
+
[[File:hai-Slide12.jpg|OLFS Log Viewer Default Page ]]
  
In the <code>$CATALINA_HOME/content/opendap/olfs.xml</code> file you will need to add (or uncomment) the following for each BES:
+
==== Log Viewer Controls ====
<pre>
 
    <adminPort>11002</adminPort>
 
</pre>
 
You will need to manually verify that the value of the adminPort element is the same as the BES.DaemonPort parameter specified in the bes.conf file for that BES instance.
 
  
==== Tomcat  Users ====
+
[[File:hai-Slide13.jpg|Log Viewer Controls 1]]
  
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.
+
[[File:hai-Slide14.jpg|Log Viewer Controls 2]]
  
[http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html Look here from more information on Tomcat and other authentication Realms]
+
==== Setting logging levels ====
  
===== how-to =====
+
[[File:hai-Slide15.jpg|Setting log levels 1]]
# Edit the file <code>$CATALINA_HOME/conf/tomcat-users.xml</code>
 
# Add a user whose role is "manager":<br/> <code><user username="admin" password="foo" roles="manager" /></code><br/>And be sure to make the password something better than "foo".
 
  
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.  
+
[[File:hai-Slide16.jpg|Setting log levels 2]]
  
==== Tomcat SSL ====
+
[[File:hai-Slide17.jpg|Setting log levels 3]]
  
In order to use the HAI you will need to configure your tomcat instance to enable SSL. How to accomplish this is covered in detail [http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html here at the Tomcat site.]
+
[[File:hai-Slide18.jpg|Setting log levels 4]]
  
===== how-to =====
+
=== BES Controls ===
From their Quick Start section:
 
  
:''To install and configure SSL support on Tomcat 6, you need to follow these simple steps. For more information, read the rest of [http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html this HOW-TO].''
+
<!-- The BES controller is located at: https://test.opendap.org:8453/opendap/docs/admin/besctl.jsp -->
  
:1. Create a certificate keystore by executing the following command:
+
The BES control panel provides one tab for each back-end server in this instance of Hyrax. Note that in these pictures we have only one BES running and it is called '/' (slash) meaning it is the default BES.
  
:Windows:
+
[[File:Besctl-01.jpg|Default Admin Page]]
:: <code>%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA</code>
 
  
:Unix:
+
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.
::<code>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</code><br/>
 
  
:and specify a password value of "changeit".
+
[[File:hai-Slide02.jpg|Admin Page Tour 1]]
  
:2. Uncomment the "SSL HTTP/1.1 Connector" entry in $CATALINA_BASE/conf/server.xml and modify as described in the [http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html#Configuration Configuration section].
+
[[File:hai-Slide03.jpg|Admin Page Tour  2]]
  
==== Olfs Details ====
+
==== BES Configuration ====
The HAI servlet (as part of the Hyrax web application) utilizes a <security-constraint> element, and a <login-config> element that define 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:
+
[[File:hai-Slide04.jpg|BES Configuration 1]]
  
 +
[[File:hai-Slide05.jpg|BES Configuration 2]]
  
    <security-constraint>
+
==== Bes Logging ====
        <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>
 
            <!-- this ensures that all efforts to access the admin interface and resources must use HTTPS -->
 
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
 
        </user-data-constraint>
 
    </security-constraint>
 
  
== Using the Hyrax Admin Interface ==
+
[[File:hai-Slide06.jpg|BES Logging 1]]
  
Note: We often refer to the interface as either the ''HAI'' or just ''the interface''.
+
[[File:hai-Slide07.jpg|BES Logging 2]]
  
To access the the interface, use the following URLs:
+
[[File:hai-Slide08.jpg|BES Logging Configuration 1]]
* <code><nowiki>https://localhost:8443/opendap/docs/admin/index.jsp</nowiki></code> or <code><nowiki>https://localhost:8443/opendap/docs/admin/</nowiki></code>
 
* <code><nowiki>http://localhost:8080/opendap/docs/admin</nowiki></code>
 
  
You will need to login using a user who is assigned the ''manager'' role as described above.
+
[[File:hai-Slide09.jpg|BES Logging 3]]
  
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.
+
==== OLFS Connections ====
  
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.
+
[[File:hai-Slide10.jpg|OLFS Connections 1]]
  
== OLFS Log Viewer ==
+
[[File:hai-Slide11.jpg|OLFS Connections 2]]
== BES Controls ==
 

Latest revision as of 20:47, 25 September 2015

1 Overview

The Hyrax Administrator's Interface (HAI) is a graphical interface to the configuration files and run-time logs of the Hyrax data server. It provides a way to start and stop different parts of Hyrax and to change their configuration files on the fly. Because Hyrax can run on several different hosts, it can be a challenge to manage; the HAI provides a single tabbed interface where the logs and configuration files for those different hosts can easily be tracked.

The HAI is a web based interface, so it can be used from any computer that can access the server using a secure connection.

The following describes the installation and configuration of the HAI followed by an explanation of its features. Note that the interface is very simple to configure in most cases - most of the steps described for Tomcat are not necessary for many sites since it's often the case that the servlet engine is already configured for SSL and has one or more users in Tomcat's manager role. Using the interface is very intuitive.

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. Be sure to skim the Configuration Notes subsection.

Prerequisites:

  • 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 be 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 7 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. For Tomcat 7, add attributes for the keystore and keystore password (e.g., keystoreFile="${user.home}/.keystore" keystorePass="changeit") to SSL HTTP/1.1 Connector entry.
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

2.2 BES

Edit the file $HYRAX_HOME/etc/bes.conf and remove the comments from the line BES.DaemonPort=11002

Restart the BES.

2.3 OLFS

Edit the file $CATALINA_HOME/content/opendap/olfs.xml and remove the comments around the line <adminPort>11002</adminPort>

2.4 Configuration notes

  1. 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.
  2. 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
  3. More about tomcat users: Tomcat supports several authentication Realms including Memory realms, databases and LDAP. We document using memory realms here because other techniques, while better in some ways, are more cumbersome. If you are using memory realms, be sure to protect the tomcat-users.xml file because it contains plain text passwords.
  4. The <security-constraint> element in the $CATALINA_HOME/opendap/WEB-INF/web.xml configuration file controls the level of access control for the HAI
  5. The role used by the HAI is set in the $CATALINA_HOME/opendap/WEB-INF/web.xml configuration file using the <auth-constraint> element. You can switch roles by changing the <role-name>.

3 Using the Hyrax Administrator's Interface

To access the Hyrax Administrator's Interface, go to the base page for your server (http://you server/opendap) and follow the link to the Hyrax Admin Interface. Following that link will present a page where you login to the interface proper. Use the username and password for a user assigned to the manager role for your Tomcat server (see the configuration information above for more information about Tomcat users and roles). Once logged in to the HAI, you will see a page with two main links; one for the Hyrax front-end and one link for the back-end servers. Together the front-end and the back-end servers make up one installation of Hyrax and they can be spread across several machines. Generally the front-end is run on a host that is outside your institution's firewall, while the back-end servers are inside that firewall on hosts where data are located. It may be helpful to review how Hyrax is structured: Hyrax is composed of one front-end server (OLFS) and one or more back-end server (BES) process.

Since there is just one instance of the front-end, it has a fairly simple control panel. The back-end servers' control panel is a little more complex because there can be many different back-end servers all part of one Hyrax installation. Use the tabs at the top of the interface to select different back-end server instances. The following sections describe both parts of the interface.

3.1 OLFS Log Viewer

The OLFS control panel provides access to the log for the front-end of Hyrax. Note that the control panel provides a way to set the logging level for individual classes that make up the front end of the server; this is very useful for debugging and testing new front-end plugins but it rarely needed in an operation setting. The default logging level shipped with the server is generally the most useful level of detail. By default the log lines are not displayed - just click the start button to see them.

OLFS Log Viewer Default Page

3.1.1 Log Viewer Controls

Log Viewer Controls 1

Log Viewer Controls 2

3.1.2 Setting logging levels

Setting log levels 1

Setting log levels 2

Setting log levels 3

Setting log levels 4

3.2 BES Controls

The BES control panel provides one tab for each back-end server in this instance of Hyrax. Note that in these pictures we have only one BES running and it is called '/' (slash) meaning it is the default BES.

Default Admin Page

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.

Admin Page Tour 1

Admin Page Tour  2

3.2.1 BES Configuration

BES Configuration 1

BES Configuration 2

3.2.2 Bes Logging

BES Logging 1

BES Logging 2

BES Logging Configuration 1

BES Logging 3

3.2.3 OLFS Connections

OLFS Connections 1

OLFS Connections 2