You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/12/20 16:31:46 UTC
git commit: [KARAF-2511] Review and update of the monitoring page of
the user guide
Updated Branches:
refs/heads/master 801a4647c -> 63b01925a
[KARAF-2511] Review and update of the monitoring page of the user guide
Project: http://git-wip-us.apache.org/repos/asf/karaf/repo
Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/63b01925
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/63b01925
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/63b01925
Branch: refs/heads/master
Commit: 63b01925a22cf49446e33cfd010506731bb2f66b
Parents: 801a464
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Fri Dec 20 16:31:05 2013 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Fri Dec 20 16:31:05 2013 +0100
----------------------------------------------------------------------
manual/src/main/webapp/_navigation.conf | 2 +-
manual/src/main/webapp/users-guide/index.conf | 2 +-
.../src/main/webapp/users-guide/monitoring.conf | 255 ++++++++++++++-----
3 files changed, 189 insertions(+), 70 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf/blob/63b01925/manual/src/main/webapp/_navigation.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/_navigation.conf b/manual/src/main/webapp/_navigation.conf
index ccc6d00..5e0113b 100644
--- a/manual/src/main/webapp/_navigation.conf
+++ b/manual/src/main/webapp/_navigation.conf
@@ -30,7 +30,7 @@ h3. [Users Guide|/users-guide/index]
-- [EJB|/users-guide/ejb]
-- [CDI|/users-guide/cdi]
-- [HA/failover and cluster|/users-guide/failover]
-- [Monitoring|/users-guide/monitoring]
+- [Monitoring and Management using JMX|/users-guide/monitoring]
- [WebConsole|/users-guide/webconsole]
- [Tuning|/users-guide/tuning]
http://git-wip-us.apache.org/repos/asf/karaf/blob/63b01925/manual/src/main/webapp/users-guide/index.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/users-guide/index.conf b/manual/src/main/webapp/users-guide/index.conf
index 7c41a66..11b24dc 100644
--- a/manual/src/main/webapp/users-guide/index.conf
+++ b/manual/src/main/webapp/users-guide/index.conf
@@ -25,6 +25,6 @@ h1. Users Guide
** [EJB|ejb]
** [CDI|cdi]
** [HA/failover and cluster|failover]
-* [Monitoring|monitoring]
+* [Monitoring and Management using JMX|monitoring]
* [WebConsole|webconsole]
* [Tuning|tuning]
http://git-wip-us.apache.org/repos/asf/karaf/blob/63b01925/manual/src/main/webapp/users-guide/monitoring.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/users-guide/monitoring.conf b/manual/src/main/webapp/users-guide/monitoring.conf
index 1b5cf6a..bb00dab 100644
--- a/manual/src/main/webapp/users-guide/monitoring.conf
+++ b/manual/src/main/webapp/users-guide/monitoring.conf
@@ -1,62 +1,148 @@
-h1. Monitoring and Administration using JMX
+h1. Monitoring and Management using JMX
-Apache Karaf provides a large set of MBeans that allow you to fully monitor and administrate Karaf using any JMX client
-(like jconsole for instance).
+Apache Karaf provides a complete JMX layer.
-You can find more or less the same actions that you can do using the shell commands on the 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.
h2. Connecting
-To connect to local karaf instances just start jconsole. It should list the local karaf instances as "org.apache.karaf.main.Main" and allow you to connect to them.
+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:
-To connect to your running remote Karaf instance via JMX you can use the following URL:
{code}
-service:jmx:rmi://localhost:44444/jndi/rmi://localhost:1099/karaf-root
+service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root
{code}
-Make sure to use the credentials you are also using to connect to via SSH
-If you are connecting to another instance of your Karaf the following will give you an impression on how this might be configured.
+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.
+
+h2. Configuration
+
+The Apache Karaf JMX management layer is configured in the {{etc/org.apache.karaf.management.cfg}} configuration file:
{code}
-service:jmx:rmi://localhost:${rmiServerPort}/jndi/rmi://localhost:${rmiRegistryPort}/karaf-${karaf.name}
+################################################################################
+#
+# 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
{code}
-The ports and the Karaf instance name are configured in the org.apache.karaf.managment.cfg file in /etc.
+* {{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.
h2. MBeans
-Apache Karaf provides the following MBeans:
-
-* org.apache.karaf:type=instances to administrate the child instances
-* org.apache.karaf:type=bundles to manipulate the OSGi bundles
-* org.apache.karaf:type=config to manipulate the Karaf configuration files (in the etc folder) and the ConfigAdmin layer
-* org.apache.karaf:type=dev to get information and manipulate the OSGi framework
-* org.apache.karaf:type=diagnostic to create information file (dump) about Karaf activity
-* org.apache.karaf:type=features to manipulate the Karaf features
-* org.apache.karaf:type=log to manipulate to logging layer
-* org.apache.karaf:type=packages to manipulate to PackageAdmin layer and get information about exported and imported packages
-* org.apache.karaf:type=services to get information about the OSGi services
-* org.apache.karaf:type=system to shutdown the Karaf container itself
-* org.apache.karaf:type=web to get information about the Web bundles (installed with the war feature)
-* org.apache.karaf:type=http to get information about the HTTP servlet
-* org.apache.karaf:type=obr to manipulate the OBR layer (installed with the obr feature)
+Apache Karaf provides a bunch of MBeans.
-h2. JMX Operations and ACL
-
-Karaf 3.x provides support of Access Control Lists (ACL) to the JMX operations. Whenever a JMX operation is invoked, the roles of the current user are checked against the required roles for this operation. This is done through a JMX interceptor which is added through the following command line option:
+The MBeans object names have the same format:
{code}
--Djavax.management.builder.initial=org.apache.karaf.management.boot.KarafMBeanServerBuilder
+org.apache.karaf:type=[feature],name=[instance]
{code}
-NB: by default, bin/karaf and Karaf service wrapper define this interceptor, so you have nothing to do.
+Installing additional Apache Karaf features and external applications can provide new MBeans.
+
+The following MBeans list is non exhaustive:
-The required roles for JMX operations are defined in configuration files in the etc folder, and read via the OSGi ConfigAdmin, as with any other configuration in this location.
+* {{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).
-The relevant configuration is prefixed with jmx.acl and based on the JMX ObjectName that it applies to.
-For example, specific configuration for a MBean with the following name: foo.bar:type=Test can be placed in a configuration file called jmx.acl.foo.bar.Test.cfg.
+h2. RBAC
-More generic configuration can be placed in the domain (e.g. jmx.acl.foo.bar.cfg) or at the top level (jmx.acl.cfg).
+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:
@@ -66,47 +152,46 @@ A simple configuration file looks like:
getVal = manager, viewer
{code}
-The system looks for required roles using the following process.
-The most specific configuration file/pid is tried first. It means that in the previous example, the jmx.acl.foo.bar.Test.cfg is looked at first.
-In this configuration, the system looks for a:
+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:
-1. Specific match for the invocation, e.g. test(int)["17"] = role1
+1. Specific match for the invocation, e.g. {{test(int)["17"] = role1}}
-2. 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.
+2. 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.
-3. Signature match for the invocation, e.g. test(int) = role3
-If matched, the search stops and the associated roles are used.
+3. Signature match for the invocation, e.g. {{test(int) = role3}}
+ If matched, the search stops and the associated roles are used.
-4. Method name match for the invocation, e.g. test = role4
-If matched, the search stops and the associated roles are used.
+4. Method name match for the invocation, e.g. {{test = role4}}
+ If matched, the search stops and the associated roles are used.
-5. 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 *.
+5. 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.
-Some configuration examples follow:
+You can find some configuration examples:
-* Only a 'manager' can call GC on the Memory MBean:
+* Only a {{manager}} can call GC on the Memory MBean:
{code}
# etc/jmx.acl.java.lang.Memory.cfg
gc = manager
{code}
-* Bundles with ID between 0 and 49 can be stopped only by an 'admin', other bundles can be stopped by a 'manager':
+* Bundles with ID between 0 and 49 can be stopped only by an {{admin}}, other bundles can be stopped by a {{manager}}:
{code}
# etc/jmx.acl.org.apache.karaf.bundles.cfg
stop(java.lang.String)[/([1-4])?([0-9]/] = admin
stop = manager
{code}
-ACLs are also included that control what can be modified through OSGi ConfigAdmin. Especially, the modification of the
-ACLs themselves is restricted. See etc/jmx.acl.org.apache.karaf.config.cfg and etc/jmx.acl.osgi.compendium.cm.cfg configuration files.
-
-etc/jmx.acl.cfg configuration file contains the global configuration for the invocation on any MBean that doesn't have a specific ACL:
+The {{etc/jmx.acl.cfg}} configuration file contains the global configuration for the invocation on any MBean that
+doesn't have a specific configuration:
{code}
# etc/jmx.acl.cfg
@@ -117,26 +202,60 @@ etc/jmx.acl.cfg configuration file contains the global configuration for the inv
* = admin
{code}
-By default, all "read-only" operations (list*, get*, is*) can be performed by a 'viewer', whereas the "read-write" operation can be performed only by an '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.
+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.
-h1. Registering user MBeans
+h2. 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.
-The Karaf container exposes an MBeanServer as an OSGI service. This server is created when Karaf boots and can be used to registers its own MBeans. The processus is really simple as it only requires that the bean/pojo of the project extend the javax.management.StandardMBean class and implements an interface where the name of the class MUST contain the extension MBean.
+But most of them can use HTTP.
-Karaf 3.x uses Aries JMX to facilitate registering MBeans. Simply publish you MBean as an OSGi service (using Blueprint for instance), providing the JMX ObjectName property:
+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.
+[Jolokia|http://www.jolokia.org/] can be installed in Apache Karaf as a remote JMX-HTTP bridge:
+
+{code}
+karaf@root()> bundle:install -s mvn:org.jolokia/jolokia-osgi/1.1.5
{code}
- <bean id="customMBean" class="...."/>
- <service ref="customMBean" auto-export="interfaces">
- <service-properties>
- <entry key="jmx.objectname" value="my.domain:type=custom,name=${karaf.name}"/>
- </service-properties>
- </service>
+By default, Jolokia is listening on the port {{8080}}. If you point a browser on [http://localhost:8080/jolokia] you will see a JSON output like:
+
{code}
+{"timestamp":1387552680,"status":200,"request":{"type":"version"},"value":{"protocol":"7.0","agent":"1.1.5","info":{"product":"felix","vendor":"Apache","version":"4.2.1"}}}
+{code}
+
+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.
-The customMBean is a simple POJO implementing the MBeanRegistration interface (and your own interface).
+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:
+
+{code}
+{
+ "type":"read",
+ "mbean":"java.lang:type=Memory",
+ "attribute":"HeapMemoryUsage",
+ "path":"used"
+}
+{code}
+
+We can send this JSON request using {{curl}} and get the result:
+
+{code}
+curl -d "{\"type\":\"read\",\"mbean\":\"java.lang:type=Memory\",\"attribute\":\"HeapMemoryUsage\",\"path\":\"used\"}" http://localhost:8080/jolokia/ && echo ""
+{code}
+
+If you want to change the Jolokia port number, and use the default Apache Karaf HTTP connector, you have to create the {{etc/org.ops4j.pax.web.cfg}} configuration file,
+and define the {{org.osgi.service.http.port}} property:
+
+{code}
+org.osgi.service.http.port=8181
+org.ops4j.pax.web.config.file=${karaf.base}/etc/jetty.xml
+{code}
+You can find details on the [Jolokia website|http://www.jolokia.org] and in the [documentation|http://www.jolokia.org/reference/html/].
\ No newline at end of file