General questions on all things hawtio.
hawtio uses the Apache 2.0 License.
It's a pluggable management console for Java stuff which supports any kind of JVM, any kind of container (Tomcat, Jetty, Karaf, JBoss, Fuse Fabric, etc), and any kind of Java technology and middleware.
See the Getting Started Guide and the Configuration Guide
Mostly hawtio just works. However, please check out the Configuration Guide to see what kinds of things you can configure via system properties, environment variables, web.xml context-params or dependency injection.
Since 1.2-M2 of hawtio we enable security by default using the underlying application container's security mechanism.
Here's how to disable security if you wish to remove the need to login to hawtio.
- Hawtio 1.5 onwards - requires Java 8.
- Hawtio 1.4 - requires Java 7 or 8.
- Hawtio 1.3 or older - supports Java 6 and 7.
The easiest thing to do is add jolokia as a java agent via a java agent command line:
java -javaagent:jolokia-agent.jar=host=0.0.0.0 -jar foo.jar
Then by default you can connect on http;//localhost:8778/jolokia to access the jolokia REST API.
Now you can use hawtio (e.g. the Google Chrome Extension or the stand alone hawtio application) to connect to it - and it then minimises the effect of hawtio/jolokia on your app (e.g. you don't need to mess about with whats inside your application or even change the classpath)
All that's required for hawtio to connect to any remote JVM is that a jolokia agent is attached to the JVM you wish to connect to. This can be done in various ways.
Firstly if you are using Fuse or Apache ActiveMQ 5.9.x or later then you already have jolokia enabled by default.
If a JVM has no jolokia agent, you can use the Local tab of the Connect menu (in 1.2.x or later of hawtio-default.war). The Local tab lists all local Java processes on the same machine (just like JConsole does).
For JVMs not running a jolokia agent already, there's a start button (on the right) which will dynamically add the jolokia JVM agent into the selected JVM process. You can then click on the Agent URL link to connect into it.
Note that the Local plugin only works when the JVM running hawtio has the hawtio-local-jvm-mbean plugin installed (which depends on the JVM finding the com.sun.tools.attach.VirtualMachine API that jconsole uses and is included in the hawtio-default.war). BTW if you don't see a Local tab inside the Conect menu in your hawtio application; check the log of your hawtio JVM; there might be a warning around com.sun.tools.attach.VirtualMachine not being available on the classpath. Or you could just try using the exectuable jar to run hawtio which seems to work on most platforms.
Note also that the Local tab only works when the process is on the same machine as the JVM running hawtio. So a safer option is just to make sure there's a jolokia agent running in each JVM you want to manage with hawtio.
There are a few different agents you can use:
- WAR agent if you are using a servlet / EE container
- OSGi agent if you are using OSGi (note that Jolokia is enabled by default in Fuse so you don't have to worry)
- JVM agent if you are using a stand alone Java process
So once you've got a jolokia agent in your JVM you can test it by accessing http://host:port/jolokia in a browser to see if you can view the JSON returned for the version information of the jolokia agent.
Assuming you have jolokia working in your JVM, then you can use the Remote tab on the Connect menu in hawtio to connect; just enter the host, port, jolokia path and user/password. Note by default only localhost is accepted to connect for security, so you need to configure hawtio.proxyWhitelist system property or proxyWhitelist init parameter on ProxyServlet in hawtio.war's WEB-INF/web.xml to explicitly allow hosts that you are connecting to.
After trying the above if you have problems connecting to your JVM, please let us know by raising an issue and we'll try to help.
Each hawtio distro has these browser based plugins inside already; plus hawtio can discover any other external plugins deployed in the same JVM too.
Then the hawtio UI updates itself in real time based on what it can find in the server side JVM it connects to. So, for example, if you connect to an empty tomcat/jetty you'll just see things like JMX and tomcat/jetty (and maybe wiki / dashboard / maven if you're using hawtio-default.war which has a few more server side plugins inside).
Then if you deploy a WAR which has ActiveMQ or Camel inside it, you should see an ActiveMQ or Camel tab appear as you deploy code which registers mbeans for ActiveMQ or Camel.
So usually, if you are interested in a particular plugin and its not visible in the hawtio UI (after checking your preferences in case you disabled it), usually you just need to deploy or add a server side plugin; which is usually a case of deploying some Java code (e.g. ActiveMQ, Camel, Infinispan etc).
Try have a look at the change log to see the latest changes in hawtio!
Try have a look at the articles and demos to see what other folks are saying about hawtio.
The hawtio help registry tries to automatically discover help data for each registered plugin even if plugins haven't specifically registered a help file.
At first a git-based wiki might not seem terribly relevant to hawtio. A wiki can be useful to document running systems and link to the various consoles, operational tools and views. Though in addition to being used for documentation, hawtio's wiki also lets you view and edit any text file; such as Camel routes, Fuse Fabric profiles, Spring XML files, Drools rulebases, etc.
From a hawtio perspective though its wiki pages can be HTML or Markdown and then be an AngularJS HTML partial. So it can include JavaScript widgets; or it can include AngularJS directives.
This lets us use HTML and Markdown files to define custom views using HTML directives (custom tags) from any hawtio plugins. Hopefully over time we can build a large library of HTML directives that folks can use inside HTML or Markdown files to show attribute values or charts from MBeans in real time, to show a panel from a dashboard, etc. Then folks can make their own mashups and happy pages showing just the information they want.
So another way to think of hawtio wiki pages is as a kind of plugin or a custom format of a dashboard page. Right now each dashboard page assumes a grid layout of rectangular widgets which you can add to and then move around. However with a wiki page you can choose to render whatever information & widgets you like in whatever layout you like. You have full control over the content and layout of the page!
Here are some sample issues on this if you want to help!
So whether the hawtio wiki is used for documentation, to link to various hawtio and external resources, to create custom mashups or happy pages or to provide new plugin views--all the content of the wiki is audited, versioned and stored in git so it's easy to see who changed what, when and to roll back changes, etc.
You can use hawtio to remote manage any ActiveMQ brokers without the need to co-install hawtio together with the ActiveMQ broker. However you can also install hawtio with the broker if you want. Dejan Bosanac blogged how to do this.
Questions relating to errors you get while using hawtio or other general questions:
An easy way is to use a plugin to reconfigure the default perspective definition. Have a look at the custom-perspective for a plugin-based solution.
From hawtio 1.2.2 onwards you can reorder and hide plugins from the preference.
Provider sun.tools.attach.WindowsAttachProvider could not be instantiated: java.lang.UnsatisfiedLinkError: no attach in java.library.path
If you see an error like this:
java.util.ServiceConfigurationError: com.sun.tools.attach.spi.AttachProvider: Provider sun.tools.attach.WindowsAttachProvider could not be instantiated: java.lang.UnsatisfiedLinkError: no attach in java.library.path
when starting up or trying the Connect/Local tab then its probably related to this issue as was found on #718.
Basically you need to make sure that you have JAVA_HOME/bin on your path. e.g. try this first before starting hawtio:
set path=%path%;%JAVA_HOME%\jre\bin
The terminal plugin may have trouble the first time in use, not being able to connect and show the terminal. Try selecting another plugin, and go back to the terminal plugin a bit later, and it then may be able to login. Also if the screen is all black, then pressing ENTER may help show the terminal.
If you use Apache ServixeMix / Karaf and you deploy a Camel XML file by copying a xml file to the deploy directory, then the deployer does not run this with proper security. So the Karaf RBAC will deny the Apache Camel plugin to query the Camel routes to gather performance counters. As deploying by using plain XML files is not recommended, then it works by using a deployment unit as a proper OSGi bundle such as a JAR or KAR file.
The reason is that there is something running in the JVM that keeps modifying the JMX tree, such as repeativily adding/removing same set of MBeans. For example Apache ActiveMQ does that when a JMS Client has been mis configured or configured without a connection pool. Because of no connection pool, then ActiveMQ JMS client creates a new connection, uses and closes the connection, and repeat that. As a net result of that, the MBean tree keeps being modified, which causes Hawtio to trigger a tree refresh. To resolve this use connection pooling with ActiveMQ - which you should always do. For an example see issue 1903 for more details and how to resolve that.
Questions on using the available plugins:
See the list of hawtio plugins
See How Plugins Work
This is a reported issue. It turns out that the standard OSGi MBeans (in the osgi.core domain) are not installed by default on GlassFish.
The workaround is to install the Gemini Management bundle then you should see the MBeans in the osgi.core domain in the JMX tree; then the OSGi tab should appear!
Questions on using Apache Camel and hawtio.
The Camel plugin currently requires that the Camel MBeans are stored using the default domain name which is org.apache.camel. So if you configure Camel to use a different name, using the mbeanObjectDomainName configuration, then the Camel plugin will not work. See details reported in ticket 1712.
The Debug and Trace tabs depend on the JMX MBeans provided by the Camel release you use.
- the Debug tab requires at least version 2.12.x or later of your Camel library to be running
- the Trace tab requires either a 2.12.x or later distro of Camel or a Fuse distro of Camel from about 2.8 or later
Questions on writing new plugins or hacking on existing ones:
If you just want to run hawtio in a JVM then please see the Getting Started section.
If you want to hack the source code then check out how to build hawtio.
Check out the Coding Conventions for our recommended approach.
Anything you like :). So long as it runs on a web browser, you're good to go. Please start contributing!
You can write hawtio plugins in anything that runs in a browser and ideally compiles to JavaScript. So use pure JavaScript, CoffeeScript, EcmaScript6-transpiler, TypeScript, GWT, Kotlin, Ceylon, ClojureScript, ScalaJS and any language that compiles to JavaScript.
So take your pick; the person who creates a plugin can use whatever language they prefer, so please contribute a new plugin :).
The only real APIs a plugin needs to worry about are AngularJS (if you want to work in the core layout rather than just be an iframe), JSON (for some pretty trivial extension points such as adding new tabs), HTML and CSS.
Check out how plugins work. You can then either:
- Fork this project and submit your plugin by creating a Github pull request then we'll include your plugin by default in the hawtio distribution.
- Make your own WAR with your plugin added (by depending on the hawtio-web.war in your pom.xml)
- Host your plugin at some canonical website (e.g. with Github pages) then submit an issue to tell us about it and we can add it to the plugin registry JSON file.
We hope that folks can just write plugins for hawtio to be able to reuse all the various plugins in hawtio.
However if you are writing your own stand alone web application using AngularJS then please check out the Hawtio Directives which you should be able to reuse in any AngularJS application