== Introduction ==
Hawk (HA Web Konsole) is a web-based GUI for managing and monitoring Pacemaker HA clusters. It is generally intended to be run on every node in the cluster, so that you can just point your web browser at any node to access it, for example:
`https://your-server:7630/`
Hawk requires users to log in prior to providing access to the cluster. The same rules apply as for the python GUI; you need to log in as a user in the `haclient` group. The easiest thing to do is assign a password to the `hacluster` user, then log in using that account. Note that you will need to configure this user account on every node you want to use Hawk on.
Once logged in, you will see a screen showing the current state of the cluster. Three views are possible (summary, tree and table), selectable with the buttons on the top right of the screen. The navigation bar down the left hand side provides access to the history explorer, setup wizard, cluster properties, resource and constraints configuration. The little tools menu next to the logout link gives you the simulator, cluster diagram and hb_report generation.
Management operations (start, stop, online, standby, etc.) can be performed by clicking the little menu icon to the right of any node or resource on the status screen.
More detailed usage documentation (including assorted screenshots) is available in the [[http://www.suse.com/documentation/sle_ha/book_sleha/?page=/documentation/sle_ha/book_sleha/data/cha_ha_configuration_hawk.html|SUSE Linux Enterprise High Availability Extension documentation]]
== Notable Features ==
* View cluster status (summary and detailed views).
* Examine potential failure scenarios via simulator mode.
* History explorer for analysis of cluster behaviour and prior failures.
* Perform regular management tasks (start, stop, move resources, put nodes on standby/maintenance, etc.)
* Configure resources, constraints, general cluster properties.
* Setup wizard for common configurations (currently web server and OCFS2 filesystem).
== Getting Hawk ==
Hawk is included in the [[https://www.suse.com/products/highavailability/|SUSE Linux Enterprise High Availability Extension]], and has also been included with [[https://www.opensuse.org/en/|openSUSE]] since openSUSE 11.4.
Hawk should generally work with Pacemaker 1.1, but please note that Hawk 0.6.x has only been extensively tested with Pacemaker >= 1.1.8. Some error codes and clone instance handling changed with that version of Pacemaker, so as a rule, for Pacemaker >= 1.1.8, you want Hawk 0.6.x, and for Pacemaker < 1.1.8, you want Hawk 0.5.x.
Recent stable packages for openSUSE 12.2, 12.3 and Tumbleweed can be found in the [[https://build.opensuse.org/project/show/network:ha-clustering:Stable|network:ha-clustering:Stable]] [[http://download.opensuse.org/repositories/network:/ha-clustering:/Stable/|repo]] on OBS. There is also a Fedora 18 build there.
Note that hawk depends on the [[http://crmsh.nongnu.org/|crm shell]] and some functions (notably the history explorer) currently require `hb_report` from cluster-glue. Builds for both the crm shell and cluster-glue can be found in the above repository.
== Hacking Hawk ==
The source is on GitHub at https://github.com/ClusterLabs/hawk - please check the README file for useful information.
== Questions, Feedback, etc. ==
Please direct comments, feedback, questions, etc. to the appropriate [[Mailing lists|mailing list(s)]] and/or [mailto:tserong@suse.com Tim Serong] (IRC nick is "tserong").
== Introduction ==
Hawk (HA Web Konsole) is a web-based GUI for Pacemaker HA clusters.
So, why another management tool, given that we already have the crm shell, the Python GUI, and DRBD MC? In order:
* We have the usual rationale for a GUI over (or in addition to) a CLI tool; it is (or should be) easier to use, for a wider audience.
* The Python GUI is not always easily installable/runnable (think: sysadmins with Windows desktops and/or people who don't want to, or can't, forward X).
* There are a number of cases where site policy prohibits ssh access to servers (which is what DRBD MC uses internally).
There are also some differing goals; Hawk is not intended to expose absolutely everything. There will be point somewhere where you have to say "and now you must learn to use a shell". Likewise, Hawk is not intended to install the base cluster stack for you (whereas DRBD MC does a good job of this).
== Project Status ==
As at 2010-05-19 (version 0.4.1), we have:
* Reasonable feature parity with crm_mon (displays node and resource status, failed ops)
* The ability to perform basic operator tasks:
** Node: standby, online, fence
** Resource: start, stop, migrate, unmigrate, clean up.
* The ability to create, edit and delete primitives, groups, clones and m/s resources.
* The ability to create, edit and delete location, colocation and ordering constraints.
* The ability to edit crm_config properties.
Hawk will show you the nodes and resources in your cluster, and some general summary information (Pacemaker version, stack, DC, etc.). Errors and failed ops appear in a red bar at the top of the display. The display of nodes and resources is collapsible (collapsed by default), but if something breaks while you're looking at it, the display will expand to show the broken nodes and/or resources.
Note that because it's possible to manipulate the cluster, you will first be presented with a login screen. The same rules apply as for the python GUI; you need to log in as a user in the "haclient" group (the easiest thing to do is assign a password to the existing "hacluster" user, then log in using that account).
== Roadmap ==
Implementation is proceeding in a staged fashion, so that we generally have something useful most of the time, rather than nothing functional for several months. Version numbers for the 0.//n//.//n// series correspond roughly to major areas of functionality:
<table>
<tr><th>Version</th><th>Features</th></tr>
<tr><td>0.1.x</td><td>Initial cluster status display & scaffolding</td></tr>
<tr><td>0.2.x</td><td>Status display comparable to <tt>crm_mon</tt> (includes failed ops)</td></tr>
<tr><td>0.3.x</td><td>Login screen, basic management operations (node online/offline/fence, resource start/stop/migrate/cleanup)</td></tr>
<tr><td>0.4.x</td><td>Cluster configuration (create/delete resources, configure cluster properties)</td></tr>
</table>
Areas of functionality coming in future versions are:
* Explore failure scenarios (shadow CIB magic to see what would happen if a node/resource failed).
For further details see [[Hawk/Design]].
== Installation ==
Hawk is intended to run on each node in your cluster. You can then access it by pointing your web browser at the IP address of any cluster node, or the address of any IPaddr(2) resource you may have configured.
=== Dependencies ===
Hawk is a Ruby on Rails app which runs from a standalone instance of lighttpd. All required Ruby gems are frozen into the Hawk package
at build time. Its runtime dependencies are thus:
* pacemaker
* lighttpd
* ruby
When building Hawk from source, you will also need:
* rubygems
* rubygem-rake
* rubygem-rails >= 2.3
* rubygem-gettext_rails
* ruby-fcgi (openSUSE/SLES only)
* fdupes (openSUSE/SLES only)
* pam-devel
* glib2-devel
* libxml2-devel
* libpacemaker-devel (openSUSE/SLES)
* pacemaker-libs-devel (Fedora)
=== Installing The Easy Way ===
Hawk 0.3 is included with [[http://www.novell.com/products/highavailability/|SLE HAE 11 SP1]] and [[http://software.opensuse.org/114/en|openSUSE 11.4]]. Hawk 0.4 packages for various SUSE distros are available in the [[https://build.opensuse.org/project/show?project=network:ha-clustering|network:ha-clustering]] and [[https://build.opensuse.org/project/show?project=network:ha-clustering:Factory|network:ha-clustering:Factory]] repositories on [[https://build.opensuse.org/|OBS]], or you can just [[http://software.opensuse.org/search?baseproject=ALL&exclude_debug=true&lang=en&p=1&q=Hawk|search for Hawk on software.opensuse.org]].
In any case, install the RPM, then run:
```
chkconfig hawk on
rchawk start
```
Then, go to:
`https://node-ip-or-hostname:7630/`
=== Installing The Other Easy Way ===
If you have a recent SUSE- or Fedora-based system, you can build
an RPM easily from the source tree:
```
hg clone http://hg.clusterlabs.org/pacemaker/hawk
cd hawk
hg update tip
make rpm
```
Then install the RPM on your cluster nodes and:
```
chkconfig hawk on
/etc/init.d/hawk start
```
Then, go to:
`https://node-ip-or-hostname:7630/`
=== The Hard Way ===
If the above RPM build doesn't work for you, you can build and install straight from the source tree, but **read the makefile first** to ensure you'll be happy with the outcome:
```
hg clone http://hg.clusterlabs.org/pacemaker/hawk
cd hawk
hg update tip
make
sudo make install
```
The above will install in `/srv/www/hawk` and run from a SUSE-style init script. To install somewhere else (e.g.: `/var/www/hawk`) and/or to use a Red Hat-style init script, try:
```
make WWW_BASE=/var/www INIT_STYLE=redhat
sudo make WWW_BASE=/var/www INIT_STYLE=redhat install
```
Finally, go to:
`https://node-ip-or-hostname:7630/`
=== A Note on SSL Certificates ===
The Hawk init script will automatically generate a self-signed SSL certificate, in `/etc/lighttpd/certs/hawk-combined.pem`. If you want to use your own certificate, simply replace this file with one of your creation. Note that this is a combined key and certificate, i.e. you'll need to `cat key cert > hawk-combined.pem`.
== Hacking Hawk ==
Hacking an instance of Hawk that was installed from an RPM is annoying, not least because you have to keep restarting it to have any changed files reloaded. Instead, it's easiest to just run it under WEBrick from within the source tree, but first you need to run `make` to build the `hawk_chkpwd` and `hawk_invoke` helper binaries, then install them setuid-root, group=haclient in /usr/sbin. You should end up with something like:
```
# ls /usr/sbin/hawk_* -l
-rwsr-x--- 1 root haclient 9884 2011-04-14 22:56 /usr/sbin/hawk_chkpwd
-rwsr-x--- 1 root haclient 9928 2011-04-14 22:56 /usr/sbin/hawk_invoke
-rwxr-xr-x 1 root root 9992 2011-04-14 22:56 /usr/sbin/hawk_monitor
```
`hawk_chkpwd` is almost identical to `unix2_chkpwd`, except it restricts acccess to users in the `haclient` group, and doesn't inject any delay when invoked by the `hacluster` user (which is the user Hawk's lighttpd instance runs as).
`hawk_invoke` allows the `hacluster` user to run a small assortment of Pacemaker CLI tools as another user in order to support Pacemaker's ACL feature. It is used by Hawk when performing various management tasks.
`hawk_monitor` is not installed setuid-root. It exists to be polled by the web browser, to facilitate near-realtime updates of the cluster status display. It is not used when running Hawk via WEBrick.
Once you've got the above built and installed, run:
```
# sudo -u hacluster hawk/script/server
```
This will give you Hawk running via HTTP (//not// HTTPS), on port 3000, e.g.:
`http://your-dev-system:3000/`
Note that automatic status updates won't work in this mode, because requests for `/monitor` aren't routed to `/usr/sbin/hawk_monitor`. To force a status update every few seconds, try:
```
http://your-dev-system:3000/main/status?update_period=5
```
Finally, an alternative to running WEBrick as hacluster (which may require fiddling with file permissions in your source directory,
depending on how restrictive your defaults are), you can just rsync the source tree to a development cluster node, then and run it as
root there.
== Comments, Feedback, Questions, Bug Reports ==
Please direct comments, feedback, questions, etc. to the [[http://oss.clusterlabs.org/mailman/listinfo/pacemaker|Pacemaker mailing list]]. Bug reports can be entered in the [[http://developerbugs.linux-foundation.org/enter_bug.cgi?product=hawk|Linux Foundation bug tracker]], but you might be better off hassling //tserong// in #linux-cluster or #linux-ha on irc://irc.freenode.org first.