| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| // |
| |
| === Monitoring and Management using JMX |
| |
| Apache Karaf provides a complete JMX layer. |
| |
| You can remotely connect to a running Apache Karaf instance using any JMX client (like jconsole). |
| |
| The Apache Karaf features provide a set of MBeans, dedicating for the monitoring and management. |
| |
| ==== Connecting |
| |
| Apache Karaf exposes a complete MBean server that you can use remotely. |
| |
| The default port number is 1099. |
| |
| The JMX URL to use by default is: |
| |
| ---- |
| service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root |
| ---- |
| |
| If don't need the remote JMX at all, users can remove |
| |
| ---- |
| -Dcom.sun.management.jmxremote |
| ---- |
| |
| from bin/karaf|bin/karaf.bat to avoid opening the RMI listening port. |
| |
| You have to provide an username and password to access to the JMX layer. |
| The JMX layer user the security framework, and so, by default, it uses the users defined in `etc/users.properties`. |
| |
| You can change the port numbers of the JMX layer in the `etc/org.apache.karaf.management.cfg` configuration file. |
| |
| ==== Configuration |
| |
| The Apache Karaf JMX management layer is configured in the `etc/org.apache.karaf.management.cfg` configuration file: |
| |
| ---- |
| ################################################################################ |
| # |
| # Licensed to the Apache Software Foundation (ASF) under one or more |
| # contributor license agreements. See the NOTICE file distributed with |
| # this work for additional information regarding copyright ownership. |
| # The ASF licenses this file to You under the Apache License, Version 2.0 |
| # (the "License"); you may not use this file except in compliance with |
| # the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| # |
| ################################################################################ |
| |
| # |
| # The properties in this file define the configuration of Apache Karaf's JMX Management |
| # |
| |
| # |
| # Port number for RMI registry connection |
| # |
| rmiRegistryPort = 1099 |
| |
| # |
| # Port number for RMI server connection |
| # |
| rmiServerPort = 44444 |
| |
| # |
| # Name of the JAAS realm used for authentication |
| # |
| jmxRealm = karaf |
| |
| # |
| # The service URL for the JMXConnectorServer |
| # |
| serviceUrl = service:jmx:rmi://0.0.0.0:${rmiServerPort}/jndi/rmi://0.0.0.0:${rmiRegistryPort}/karaf-${karaf.name} |
| |
| # |
| # Whether any threads started for the JMXConnectorServer should be started as daemon threads |
| # |
| daemon = true |
| |
| # |
| # Whether the JMXConnectorServer should be started in a separate thread |
| # |
| threaded = true |
| |
| # |
| # The ObjectName used to register the JMXConnectorServer |
| # |
| objectName = connector:name=rmi |
| |
| # |
| # Role name used for JMX access authorization |
| # If not set, this defaults to the ${karaf.admin.role} configured in etc/system.properties |
| # |
| # jmxRole=admin |
| ---- |
| |
| * `rmiRegistryPort` property contains the port number of the JMX RMI registry. Default is `1099`. |
| * `rmiServerPort` property contains the port number of the JMX RMI server. Default is `44444`. |
| * `jmxRealm` is the security realm to use as authentication backend. By default it uses the `karaf` realm. |
| |
| ==== MBeans |
| |
| Apache Karaf provides a bunch of MBeans. |
| |
| The MBeans object names have the same format: |
| |
| ---- |
| org.apache.karaf:type=[feature],name=[instance] |
| ---- |
| |
| Installing additional Apache Karaf features and external applications can provide new MBeans. |
| |
| The following MBeans list is non exhaustive: |
| |
| * `org.apache.karaf:type=bundle,name=*`: management of the OSGi bundles. |
| * `org.apache.karaf:type=config,name=*`: management of the configurations. |
| * `org.apache.karaf:type=diagnostic,name=*`: creation of dumps containing the current Apache Karaf activity (used for diagnostic). |
| * `org.apache.karaf:type=feature,name=*`: management of the Apache Karaf features. |
| * `org.apache.karaf:type=http,name=*`: management of the HTTP service (provided by the `http` feature). |
| * `org.apache.karaf:type=instance,name=*`: management of the instances. |
| * `org.apache.karaf:type=jdbc,name=*`: management of the JDBC service (provided by the `jdbc` feature). |
| * `org.apache.karaf:type=jms,name=*`: management of the JMS service (provided by the `jms` feature). |
| * `org.apache.karaf:type=jndi,name=*`: management of the JNDI service (provided by the `jndi` feature). |
| * `org.apache.karaf:type=kar,name=*`: management of the KAR file. |
| * `org.apache.karaf:type=log,name=*`: management of the log service. |
| * `org.apache.karaf:type=obr,name=*`: management of the OBR service (provided by the `obr` feature). |
| * `org.apache.karaf:type=package,name=*`: details about packages exported/imported. |
| * `org.apache.karaf:type=service,name=*`: management of the OSGi services. |
| * `org.apache.karaf:type=system,name=*`: management of the Apache Karaf container itself (halt, restart, etc). |
| * `org.apache.karaf:type=web,name=*`: management of WebApplications (provided by the `war` feature). |
| * `org.apache.karaf:type=wrapper,name=*`: management of the service wrapper (provided by the `wrapper` feature). |
| |
| ==== RBAC |
| |
| Apache Karaf provides a complete Role-Based Access Control to the JMX MBeans and operations. |
| |
| Whenever a JMX operation is invoked, the roles of the user are checked against the required roles for this operation. |
| |
| The access lists are defined in configuration file in the `etc` folder. |
| |
| The relevant configuration is prefixed with `jmx.acl` and based on the JMX ObjectName that it applies to. |
| |
| For instance, specific configuration for a MBean with the object name `foo.bar:type=Test` can be placed in the |
| `etc/jmx.acl.foo.bar.Test.cfg` configuration file. |
| |
| More generic configurations can be placed in the domain (e.g. jmx.acl.foo.bar.cfg) or at the top level (jmx.acl.cfg). |
| |
| A simple configuration file looks like: |
| |
| ---- |
| # operation = role |
| test = admin |
| getVal = manager, viewer |
| ---- |
| |
| Apache Karaf looks for required roles using the following process |
| . |
| The most specific configuration file is tried first. It means that in the previous example, the `etc/jmx.acl.foo.bar.Test.cfg` is looked at first. |
| In this configuration, Apache Karaf looks for a: |
| |
| . Specific match for the invocation, e.g. `test(int)["17"] = role1` |
| |
| . Regex match for the invocation, e.g. `test(int)[/[0-9]/] = role2` |
| In both cases, the passed argument is converted to a String for the comparison. |
| If any of the above match, the search stops and the associated roles are used. |
| |
| . Signature match for the invocation, e.g. `test(int) = role3` |
| If matched, the search stops and the associated roles are used. |
| |
| . Method name match for the invocation, e.g. `test = role4` |
| If matched, the search stops and the associated roles are used. |
| |
| . A method name wildcard match, e.g. `te* = role5` |
| For all the wildcard matches found in the current configuration file, the roles associated with the longest match are used. |
| So if you have te* and * and the method invoked is 'test', then the roles defined with te* are used, not the ones defined with *. |
| |
| If no matching definition is found, the most specific definition always takes the precedence. |
| |
| You can find some configuration examples: |
| |
| * Only a `manager` can call GC on the Memory MBean: |
| |
| ---- |
| # etc/jmx.acl.java.lang.Memory.cfg |
| gc = manager |
| ---- |
| |
| * Bundles with ID between 0 and 49 can be stopped only by an `admin`, other bundles can be stopped by a `manager`: |
| |
| ---- |
| # etc/jmx.acl.org.apache.karaf.bundles.cfg |
| stop(java.lang.String)[/([1-4])?([0-9]/] = admin |
| stop = manager |
| ---- |
| |
| The `etc/jmx.acl.cfg` configuration file contains the global configuration for the invocation on any MBean that |
| doesn't have a specific configuration: |
| |
| ---- |
| # etc/jmx.acl.cfg |
| list* = viewer |
| get* = viewer |
| is* = viewer |
| set* = admin |
| * = admin |
| ---- |
| |
| By default, all "read-only" operations (`list*`, `get*`, `is*`) can be performed by a `viewer`, whereas the "read-write" operations can be performed only by an `admin`. |
| |
| The `org.apache.karaf:type=security,area=jmx` MBean can be used to check whether the current user can access a certain MBean or invoke a specific operation on it. |
| This MBean can be used by management clients (monitoring tools, etc) to decide whether to show certain MBeans or operations to the end user. |
| |
| ==== JMX-HTTP bridge with Jolokia |
| |
| It's not always easy to use a JMX client with the RMI protocol. |
| |
| Some monitoring tools (Nagios, Zabbix, ...) are not native JMX clients. |
| |
| But most of them can use HTTP. |
| |
| More over, you may want to write your own application/web application. In that case, HTTP and JSON can be very interesting and easy to remotely manage Apache Karaf. |
| |
| http://www.jolokia.org/[Jolokia] can be installed in Apache Karaf as a remote JMX-HTTP bridge. |
| |
| Karaf provides a jolokia feature, ready to install: |
| |
| ---- |
| karaf@root()> feature:install jolokia |
| ---- |
| |
| By default, Jolokia is listening on the port `8181` (see the link:webcontainer[WebContainer (JSP/Servlet)] page for details about the HTTP configuration). |
| |
| If you point a browser on http://localhost:8181/jolokia you will see a JSON output like: |
| |
| ---- |
| {"timestamp":1421765829,"status":200,"request":{"type":"version"},"value":{"protocol":"7.2","config":{"useRestrictorService":"false","canonicalNaming":"true","includeStackTrace":"true","listenForHttpService":"true","historyMaxEntries":"10","agentId":"192.168.134.10-5922-6eb8d517-osgi","debug":"false","realm":"karaf","serializeException":"false","agentContext":"\/jolokia","agentType":"servlet","policyLocation":"classpath:\/jolokia-access.xml","user":"karaf","debugMaxEntries":"100","authMode":"jaas","mimeType":"text\/plain"},"agent":"1.2.4-SNAPSHOT","info":{"product":"felix","vendor":"Apache","version":"4.4.1"`} |
| ---- |
| |
| You can manipulate the Apache Karaf JMX layer via HTTP and JSON, via system tools (like `curl`, `jmx4perl`, monitoring tools (supporting HTTP/JSON), or web applications. |
| |
| For instance, you can send a JSON request to get details about the current Apache Karaf heap memory usage. |
| |
| The format of the request is: |
| |
| ---- |
| { |
| "type":"read", |
| "mbean":"java.lang:type=Memory", |
| "attribute":"HeapMemoryUsage", |
| "path":"used" |
| } |
| ---- |
| |
| We can send this JSON request using `curl` and get the result: |
| |
| ---- |
| curl -u karaf -d "{\"type\":\"read\",\"mbean\":\"java.lang:type=Memory\",\"attribute\":\"HeapMemoryUsage\",\"path\":\"used\"}" http://localhost:8181/jolokia/ && echo "" |
| Enter host password for user 'karaf': |
| {"timestamp":1421765948,"status":200,"request":{"mbean":"java.lang:type=Memory","path":"used","attribute":"HeapMemoryUsage","type":"read"},"value":69121000} |
| ---- |
| |
| You can find details on the http://www.jolokia.org[Jolokia website] and in the http://www.jolokia.org/reference/html/[documentation]. |
| |
| ==== Apache Karaf Decanter |
| |
| Apache Karaf Decanter provides a complete monitoring solution including data history, turnkey dashboards, SLA and alerting support. |