http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/log.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/log.adoc b/manual/src/main/asciidoc/users-guide/log.adoc deleted file mode 100644 index 95c3304..0000000 --- a/manual/src/main/asciidoc/users-guide/log.adoc +++ /dev/null @@ -1,565 +0,0 @@ -// -// 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. -// - -= Log - -Apache Karaf provides a very dynamic and powerful logging system. - -It supports: - -* the OSGi Log Service -* the Apache Log4j framework -* the Apache Commons Logging framework -* the Logback framework -* the SLF4J framework -* the native Java Util Logging framework - -It means that the applications can use any logging framework, Apache Karaf will use the central log system to manage the -loggers, appenders, etc. - -== Configuration files - -The initial log configuration is loaded from `etc/org.ops4j.pax.logging.cfg`. - -This file is a [standard Log4j configuration file|http://logging.apache.org/log4j/1.2/manual.html]. - -You find the different Log4j element: - -* loggers -* appenders -* layouts - -You can add your own initial configuration directly in the file. - -The default configuration is the following: - ----- -################################################################################ -# -# 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. -# -################################################################################ - -# Root logger -log4j.rootLogger=INFO, out, osgi:* -log4j.throwableRenderer=org.apache.log4j.OsgiThrowableRenderer - -# CONSOLE appender not used by default -log4j.appender.stdout=org.apache.log4j.ConsoleAppender -log4j.appender.stdout.layout=org.apache.log4j.PatternLayout -log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n - -# File appender -log4j.appender.out=org.apache.log4j.RollingFileAppender -log4j.appender.out.layout=org.apache.log4j.PatternLayout -log4j.appender.out.layout.ConversionPattern=%d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n -log4j.appender.out.file=${karaf.data}/log/karaf.log -log4j.appender.out.append=true -log4j.appender.out.maxFileSize=1MB -log4j.appender.out.maxBackupIndex=10 - -# Sift appender -log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender -log4j.appender.sift.key=bundle.name -log4j.appender.sift.default=karaf -log4j.appender.sift.appender=org.apache.log4j.FileAppender -log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout -log4j.appender.sift.appender.layout.ConversionPattern=%d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %m%n -log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log -log4j.appender.sift.appender.append=true ----- - -The default configuration only define the `ROOT` logger, with `INFO` log level, using the `out` file appender. -You can change the log level to any Log4j valid values (from the most to less verbose): TRACE, DEBUG, INFO, WARN, ERROR, FATAL. - -The `osgi:*` appender is a special appender to send the log message to the OSGi Log Service. - -A `stdout` console appender is pre-configured, but not enabled by default. This appender allows you to display log -messages directly to standard output. It's interesting if you plan to run Apache Karaf in server mode (without console). - -To enable it, you have to add the `stdout` appender to the `rootLogger`: - ----- -log4j.rootLogger=INFO, out, stdout, osgi:* ----- - -The `out` appender is the default one. It's rolling file appender that maintain and rotate 10 log files of 1MB each. -The log files are located in `data/log/karaf.log` by default. - -The `sift` appender is not enabled by default. This appender allows you to have one log file per deployed bundle. -By default, the log file name format uses the bundle symbolic name (in the `data/log` folder). - -You can edit this file at runtime: any change will be reloaded and be effective immediately (no need to restart Apache Karaf). - -Another configuration file is used by Apache Karaf: `etc/org.apache.karaf.log.cfg`. This files configures the Log Service -used by the log commands (see later). - -== Commands - -Instead of changing the `etc/org.ops4j.pax.logging.cfg` file, Apache Karaf provides a set of commands allowing to -dynamically change the log configuration and see the log content: - -=== `log:clear` - -The `log:clear` command clears the log entries. - -=== `log:display` - -The `log:display` command displays the log entries. - -By default, it displays the log entries of the `rootLogger`: - ----- -karaf@root()> log:display -2013-11-29 19:12:46,208 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.9.0 | BouncyCastle not registered, using the default JCE provider -2013-11-29 19:12:47,368 | INFO | FelixStartLevel | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Starting JMX OSGi agent ----- - -You can also display the log entries from a specific logger, using the `logger` argument: - ----- -karaf@root()> log:display ssh -2013-11-29 19:12:46,208 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.9.0 | BouncyCastle not registered, using the default JCE provider ----- - -By default, all log entries will be displayed. It could be very long if your Apache Karaf container is running since a long time. -You can limit the number of entries to display using the `-n` option: - ----- -karaf@root()> log:display -n 5 -2013-11-30 06:53:24,143 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.BundleStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=bundleState,version=1.7,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1 -2013-11-30 06:53:24,150 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.PackageStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=packageState,version=1.5,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1 -2013-11-30 06:53:24,150 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.ServiceStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=serviceState,version=1.7,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1 -2013-11-30 06:53:24,152 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.wiring.BundleWiringStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=wiringState,version=1.1,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1 -2013-11-30 06:53:24,530 | INFO | FelixStartLevel | RegionsPersistenceImpl | 78 - org.apache.karaf.region.persist - 3.0.0 | Loading region digraph persistence ----- - -You can also limit the number of entries stored and retain using the `size` property in `etc/org.apache.karaf.log.cfg` file: - ----- -# -# The number of log statements to be displayed using log:display. It also defines the number -# of lines searched for exceptions using log:display exception. You can override this value -# at runtime using -n in log:display. -# -size = 500 ----- - -By default, each log level is displayed with a different color: ERROR/FATAL are in red, DEBUG in purple, INFO in cyan, etc. -You can disable the coloring using the `--no-color` option. - -The log entries format pattern doesn't use the conversion pattern define in `etc/org.ops4j.pax.logging.cfg` file. -By default, it uses the `pattern` property defined in `etc/org.apache.karaf.log.cfg`. - ----- -# -# The pattern used to format the log statement when using log:display. This pattern is according -# to the log4j layout. You can override this parameter at runtime using log:display with -p. -# -pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n ----- - -You can also change the pattern dynamically (for one execution) using the `-p` option: - ----- -karaf@root()> log:display -p "%d - %c - %m%n" -2013-11-30 07:01:58,007 - org.apache.sshd.common.util.SecurityUtils - BouncyCastle not registered, using the default JCE provider -2013-11-30 07:01:58,725 - org.apache.aries.jmx.core - Starting JMX OSGi agent -2013-11-30 07:01:58,744 - org.apache.aries.jmx.core - Registering MBean with ObjectName [osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=6361fc65-8df4-4886-b0a6-479df2d61c83] for service with service.id [13] -2013-11-30 07:01:58,747 - org.apache.aries.jmx.core - Registering org.osgi.jmx.service.cm.ConfigurationAdminMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=6361fc65-8df4-4886-b0a6-479df2d61c83 ----- - -The pattern is a regular Log4j pattern where you can use keywords like %d for the date, %c for the class, %m for the log -message, etc. - -=== `log:exception-display` - -The `log:exception-display` command displays the last occurred exception. - -As for `log:display` command, the `log:exception-display` command uses the `rootLogger` by default, but you can -specify a logger with the `logger` argument. - -=== `log:get` - -The `log:get` command show the current log level of a logger. - -By default, the log level showed is the one from the root logger: - ----- -karaf@root()> log:get -Logger | Level --------------- -ROOT | INFO ----- - -You can specify a particular logger using the `logger` argument: - ----- -karaf@root()> log:get ssh -Logger | Level --------------- -ssh | INFO ----- - -The `logger` argument accepts the `ALL` keyword to display the log level of all logger (as a list). - -For instance, if you have defined your own logger in `etc/org.ops4j.pax.logging.cfg` file like this: - ----- -log4j.logger.my.logger = DEBUG ----- - -you can see the list of loggers with the corresponding log level: - ----- -karaf@root()> log:get ALL -Logger | Level ------------------ -ROOT | INFO -my.logger | DEBUG ----- - -The `log:list` command is an alias to `log:get ALL`. - -=== `log:log` - -The `log:log` command allows you to manually add a message in the log. It's interesting when you create Apache Karaf -scripts: - ----- -karaf@root()> log:log "Hello World" -karaf@root()> log:display -2013-11-30 07:20:16,544 | INFO | Local user karaf | command | 59 - org.apache.karaf.log.command - 3.0.0 | Hello World ----- - -By default, the log level is INFO, but you can specify a different log level using the `-l` option: - ----- -karaf@root()> log:log -l ERROR "Hello World" -karaf@root()> log:display -2013-11-30 07:21:38,902 | ERROR | Local user karaf | command | 59 - org.apache.karaf.log.command - 3.0.0 | Hello World ----- - -=== `log:set` - -The `log:set` command sets the log level of a logger. - -By default, it changes the log level of the `rootLogger`: - ----- -karaf@root()> log:set DEBUG -karaf@root()> log:get -Logger | Level --------------- -ROOT | DEBUG ----- - -You can specify a particular logger using the `logger` argument, after the `level` one: - ----- -karaf@root()> log:set INFO my.logger -karaf@root()> log:get my.logger -Logger | Level ------------------ -my.logger | INFO ----- - -The `level` argument accepts any Log4j log level: TRACE, DEBUG, INFO, WARN, ERROR, FATAL. - -By it also accepts the DEFAULT special keyword. - -The purpose of the DEFAULT keyword is to delete the current level of the logger (and only the level, the other properties -like appender are not deleted) -in order to use the level of the logger parent (logger are hierarchical). - -For instance, you have defined the following loggers (in `etc/org.ops4j.pax.logging.cfg` file): - ----- -rootLogger=INFO,out,osgi:* -my.logger=INFO,appender1 -my.logger.custom=DEBUG,appender2 ----- - -You can change the level of `my.logger.custom` logger: - ----- -karaf@root()> log:set INFO my.logger.custom ----- - -Now we have: - ----- -rootLogger=INFO,out,osgi:* -my.logger=INFO,appender1 -my.logger.custom=INFO,appender2 ----- - -You can use the DEFAULT keyword on `my.logger.custom` logger to remove the level: - ----- -karaf@root()> log:set DEFAULT my.logger.custom ----- - -Now we have: - ----- -rootLogger=INFO,out,osgi:* -my.logger=INFO,appender1 -my.logger.custom=appender2 ----- - -It means that, at runtime, the `my.logger.custom` logger uses the level of its parent `my.logger`, so `INFO`. - -Now, if we use DEFAULT keyword with the `my.logger` logger: - ----- -karaf@root()> log:set DEFAULT my.logger ----- - -We have: - ----- -rootLogger=INFO,out,osgi:* -my.logger=appender1 -my.logger.custom=appender2 ----- - -So, both `my.logger.custom` and `my.logger` use the log level of the parent `rootLogger`. - -It's not possible to use DEFAULT keyword with the `rootLogger` and it doesn't have parent. - -=== `log:tail` - -The `log:tail` is exactly the same as `log:display` but it continuously displays the log entries. - -You can use the same options and arguments as for the `log:display` command. - -By default, it displays the entries from the `rootLogger`: - ----- -karaf@root()> log:tail -2013-11-30 07:40:28,152 | INFO | FelixStartLevel | SecurityUtils | 16 - org.apache.sshd.core - 0.9.0 | BouncyCastle not registered, using the default JCE provider -2013-11-30 07:40:28,909 | INFO | FelixStartLevel | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Starting JMX OSGi agent -2013-11-30 07:40:28,928 | INFO | FelixStartLevel | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering MBean with ObjectName [osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=b44a44b7-41cd-498f-936d-3b12d7aafa7b] for service with service.id [13] -2013-11-30 07:40:28,936 | INFO | JMX OSGi Agent | core | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.service.cm.ConfigurationAdminMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=b44a44b7-41cd-498f-936d-3b12d7aafa7b ----- - -To exit from the `log:tail` command, just type CTRL-C. - -== JMX LogMBean - -All actions that you can perform with the `log:*` command can be performed using the LogMBean. - -The LogMBean object name is `org.apache.karaf:type=log,name=*`. - -=== Attributes - -* `Level` attribute is the level of the ROOT logger. - -=== Operations - -* `getLevel(logger)` to get the log level of a specific logger. As this operation supports the ALL keyword, it returns a Map with the level of each logger. -* `setLevel(level, logger)` to set the log level of a specific logger. This operation supports the DEFAULT keyword as for the `log:set` command. - -== Advanced configuration - -=== Filters - -You can use filters on appender. Filters allow log events to be evaluated to determine if or how they should be published. - -Log4j provides ready to use filters: - -* The DenyAllFilter (`org.apache.log4j.varia.DenyAllFilter`) drops all logging events. - You can add this filter to the end of a filter chain to switch from the default "accept all unless instructed otherwise" - filtering behaviour to a "deny all unless instructed otherwise" behaviour. -* The LevelMatchFilter (`org.apache.log4j.varia.LevelMatchFilter` is a very simple filter based on level matching. - The filter admits two options `LevelToMatch` and `AcceptOnMatch`. If there is an exact match between the value of - the `LevelToMatch` option and the level of the logging event, then the event is accepted in case the `AcceptOnMatch` - option value is set to `true`. Else, if the `AcceptOnMatch` option value is set to `false`, the log event is rejected. -* The LevelRangeFilter (`org.apache.log4j.varia.LevelRangeFilter` is a very simple filter based on level matching, - which can be used to reject messages with priorities outside a certain range. The filter admits three options `LevelMin`, - `LevelMax` and `AcceptOnMatch`. If the log event level is between `LevelMin` and `LevelMax`, the log event is - accepted if `AcceptOnMatch` is true, or rejected if `AcceptOnMatch` is false. -* The StringMatchFilter (`org.apache.log4j.varia.StringMatchFilter`) is a very simple filter based on string matching. - The filter admits two options `StringToMatch` and `AcceptOnMatch`. If there is a match between the `StringToMatch` - and the log event message, the log event is accepted if `AcceptOnMatch` is true, or rejected if `AcceptOnMatch` is false. - -The filter is defined directly on the appender, in the `etc/org.ops4j.pax.logging.cfg` configuration file. - -The format to use it: - ----- -log4j.appender.[appender-name].filter.[filter-name]=[filter-class] -log4j.appender.[appender-name].filter.[filter-name].[option]=[value] ----- - -For instance, you can use the `f1` LevelRangeFilter on the `out` default appender: - ----- -log4j.appender.out.filter.f1=org.apache.log4j.varia.LevelRangeFilter -log4j.appender.out.filter.f1.LevelMax=FATAL -log4j.appender.out.filter.f1.LevelMin=DEBUG ----- - -Thanks to this filter, the log files generated by the `out` appender will contain only log messages with a level -between DEBUG and FATAL (the log events with TRACE as level are rejected). - -=== Nested appenders - -A nested appender is a special kind of appender that you use "inside" another appender. -It allows you to create some kind of "routing" between a chain of appenders. - -The most used "nested compliant" appender are: - -* The AsyncAppender (`org.apache.log4j.AsyncAppender`) logs events asynchronously. This appender collects the events - and dispatch them to all the appenders that are attached to it. -* The RewriteAppender (`org.apache.log4j.rewrite.RewriteAppender`) forwards log events to another appender after possibly - rewriting the log event. - -This kind of appender accepts an `appenders` property in the appender definition: - ----- -log4j.appender.[appender-name].appenders=[comma-separated-list-of-appender-names] ----- - -For instance, you can create a AsyncAppender named `async` and asynchronously dispatch the log events to a JMS appender: - ----- -log4j.appender.async=org.apache.log4j.AsyncAppender -log4j.appender.async.appenders=jms - -log4j.appender.jms=org.apache.log4j.net.JMSAppender -... ----- - -=== Error handlers - -Sometime, appenders can fail. For instance, a RollingFileAppender tries to write on the filesystem but the filesystem is full, or a JMS appender tries to send a message but the JMS broker is not there. - -As log can be very critical to you, you have to be inform that the log appender failed. - -It's the purpose of the error handlers. Appenders may delegate their error handling to error handlers, giving a chance to react to this appender errors. - -You have two error handlers available: - -* The OnlyOnceErrorHandler (`org.apache.log4j.helpers.OnlyOnceErrorHandler`) implements log4j's default error handling policy - which consists of emitting a message for the first error in an appender and ignoring all following errors. The error message - is printed on `System.err`. - This policy aims at protecting an otherwise working application from being flooded with error messages when logging fails. -* The FallbackErrorHandler (`org.apache.log4j.varia.FallbackErrorHandler`) allows a secondary appender to take over if the primary appender fails. - The error message is printed on `System.err`, and logged in the secondary appender. - -You can define the error handler that you want to use for each appender using the `errorhandler` property on the appender definition itself: - ----- -log4j.appender.[appender-name].errorhandler=[error-handler-class] -log4j.appender.[appender-name].errorhandler.root-ref=[true|false] -log4j.appender.[appender-name].errorhandler.logger-ref=[logger-ref] -log4j.appender.[appender-name].errorhandler.appender-ref=[appender-ref] ----- - -=== OSGi specific MDC attributes - -The `sift` appender is a OSGi oriented appender allowing you to split the log events based on MDC (Mapped Diagnostic Context) attributes. - -MDC allows you to distinguish the different source of log events. - -The `sift` appender provides OSGi oritend MDC attributes by default: - -* `bundle.id` is the bundle ID -* `bundle.name` is the bundle symbolic name -* `bundle.version` is the bundle version - -You can use these MDC properties to create a log file per bundle: - ----- -log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender -log4j.appender.sift.key=bundle.name -log4j.appender.sift.default=karaf -log4j.appender.sift.appender=org.apache.log4j.FileAppender -log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout -log4j.appender.sift.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n -log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log -log4j.appender.sift.appender.append=true ----- - -=== Enhanced OSGi stack trace renderer - -By default, Apache Karaf provides a special stack trace renderer, adding some OSGi specific specific information. - -In the stack trace, in addition of the class throwing the exception, you can find a pattern `[id:name:version]` at the -end of each stack trace line, where: - -* `id` is the bundle ID -* `name` is the bundle name -* `version` is the bundle version - -It's very helpful to diagnosing the source of an issue. - -For instance, in the following IllegalArgumentException stack trace, we can see the OSGi details about the source of the exception: - ----- -java.lang.IllegalArgumentException: Command not found: *:foo - at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:225)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:162)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.felix.gogo.runtime.shell.Pipe.run(Pipe.java:101)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:79)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.felix.gogo.runtime.shell.CommandSessionImpl.execute(CommandSessionImpl.java:71)[21:org.apache.karaf.shell.console:3.0.0] - at org.apache.karaf.shell.console.jline.Console.run(Console.java:169)[21:org.apache.karaf.shell.console:3.0.0] - at java.lang.Thread.run(Thread.java:637)[:1.7.0_21] ----- - -=== Custom appenders - -You can use your own appenders in Apache Karaf. - -The easiest way to do that is to package your appender as an OSGi bundle and attach it as a fragment of the -`org.ops4j.pax.logging.pax-logging-service` bundle. - -For instance, you create `MyAppender`: - ----- -public class MyAppender extends AppenderSkeleton { -... -} ----- - -You compile and package as an OSGi bundle containing a MANIFEST looking like: - ----- -Manifest: -Bundle-SymbolicName: org.mydomain.myappender -Fragment-Host: org.ops4j.pax.logging.pax-logging-service -... ----- - -Copy your bundle in the Apache Karaf `system` folder. The `system` folder uses a standard Maven directory layout: groupId/artifactId/version. - -In the `etc/startup.properties` configuration file, you define your bundle in the list before the pax-logging-service bundle. - -You have to restart Apache Karaf with a clean run (purging the `data` folder) in order to reload the system bundles. -You can now use your appender directly in `etc/org.ops4j.pax.logging.cfg` configuration file.
http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/migration.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/migration.adoc b/manual/src/main/asciidoc/users-guide/migration.adoc deleted file mode 100644 index f4d30a1..0000000 --- a/manual/src/main/asciidoc/users-guide/migration.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// -// 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. -// - -= Migration from Karaf 2.x to 3.x - -This section shows the necessary changes you have to consider when upgrading karaf. - -== Updating an existing instance - -There is no simple upgrade path for an existing instance. The simplest way of upgraing is to redeploy your application to the new karaf instance and copy over the changed configurations. - -== Changes in command names - -In general the command names now have the scheme <object in singular>:<command on object>. -For cases when one scope cares for more than one object type like feature:* that cares for features and feature repositories the sheme is partly: <scope>:<object-command>. -The following table shows side by side the old and new command names. - -|| Name 2.x || Name 3.x || -| features:add-url | feature:repo-add | -| features:chooseurl | feature:repo-add | -| features:chooseurl | feature:repo-add | -| features:listrepositories | feature:repo-list | -| features:listurl | feature:repo-list | -| features:listversions | feature:version-list | -| features:refreshurl | feature:repo-add | -| features:removerepository | feature:repo-remove | -| features:removeurl | feature:repo-remove | -| features:* | feature:* | -| osgi:* | bundle:* | -| dev:dynamic-import | bundle:dynamic-import | -| dev:framework | system:framework | -| dev:print-stack-traces | shell:print-stack-traces | -| dev:restart | system:shutdown -r | -| dev:show-tree | bundle:tree-show | -| dev:watch | bundle:watch | -| admin:* | instance:* | -| config: | config: | -| jaas: | jaas: | - -== Changes in MBeans - -For Karaf 3 we did a major refactoring of the module and package structure of Karaf. So almost all mbean interfaces moved to a new package. So if you use the Java interface to access an mbean you will most likely have to change that. - -Like the commands the bean types have bean renamed to the singular form: - -|| Type Karaf 2.x || Type Karaf 3.x || -| admin | instance | -| bundles | bundle | -| features | feature | -| packages | package | -| services | service | - -Besides the type in the objectname a lot of the operations / attributes changed. - - http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/monitoring.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/monitoring.adoc b/manual/src/main/asciidoc/users-guide/monitoring.adoc deleted file mode 100644 index 7afcf4b..0000000 --- a/manual/src/main/asciidoc/users-guide/monitoring.adoc +++ /dev/null @@ -1,273 +0,0 @@ -// -// 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 ----- - -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: - -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. - -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. - -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. - -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. - -[Jolokia|http://www.jolokia.org/] 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 [WebContainer (JSP/Servlet)|webcontainer] 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 [Jolokia website|http://www.jolokia.org] and in the [documentation|http://www.jolokia.org/reference/html/]. http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/obr.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/obr.adoc b/manual/src/main/asciidoc/users-guide/obr.adoc deleted file mode 100644 index ce40226..0000000 --- a/manual/src/main/asciidoc/users-guide/obr.adoc +++ /dev/null @@ -1,373 +0,0 @@ -// -// 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. -// - -= OBR - -The goal of OBR (OSGi Bundle Repository) is: - -1. to simplify deploying and using bundles -2. to encourage independent bundle development. - -OBR achieves the first goal by providing a service that can automatically install a bundle, with its deployment dependencies, -from a bundle repository. This makes it easier for people to experiment with existing bundles. - -The second goal is achieved by raising the visibility of the available bundles in a repository. - -OBR is an optional Apache Karaf feature. You have to install the `obr` feature to use OBR service: - ----- -karaf@root()> feature:install obr ----- - -The OBR feature turns Apache Karaf as an OBR client. It means that Apache Karaf can use a OBR repository to the installation -of the bundles, and during the installation of the features. - -The installation of the `obr` feature adds in Apache Karaf: - -* the OBR service -* the features OBR resolver -* the `obr:*` commands -* the JMX ObrMBean - -The OBR repository contains all bundles. The OBR service knows all requirements and capabilities of each bundle on an -OBR repository (it's the OBR metadata). - -Thanks to that, when you install ("deploy" in OBR wording) a bundle using the OBR service, it looks for all bundles -providing the capabilities matching the bundle requirements. -It will automatically install the bundles needed for the bundle. - -== Features OBR resolver - -If the feature specifies `obr` in the `resolver` attribute, Apache Karaf can use the OBR service to construct the list -of bundles to install with the features. - -The feature default resolver just consider the bundles described in the feature itself. - -Using the OBR resolver, Apache Karaf can extend the bundle list at the feature installation time using the OBR service. - -== Commands - -=== `obr:url-add` - -The `obr:url-add` command registers the OBR repository at a given URL in the OBR service. - -Basically, an OBR repository is described by a `repository.xml` file. - -The `obr:url-add` command expects an `url` argument. The `url` argument is the URL to the OBR repository `repository.xml` file. -Any URL described in the [Artifacts repositories and URLs section|urls] is supported. - -For instance: - ----- -karaf@root()> obr:url-add file:///user/.m2/repository/repository.xml ----- - -=== `obr:url-list` - -The `obr:url-list` command lists the OBR repository (with URL) registered in the OBR service: - ----- -karaf@root()> obr:url-list -Index | OBR URL ---------------------------------------------------------- -0 | file:/user/.m2/repository/repository.xml ----- - -=== `obr:url-refresh` - -The `obr:url-refresh` command refresh an OBR repository (reloading the URL). - -The OBR service doesn't take "on the fly" the changes performed on an OBR repository `repository.xml`. You have to -reload the `repository.xml` URL to take the changes. It's the purpose of the `obr:url-refresh` command. - -Without argument, the `obr:url-refresh` command refreshes all repositories: - ----- -karaf@root()> obr:url-refresh ----- - -You can refresh only one repository by specifying the URL as argument: - ----- -karaf@root()> obr:url-refresh file:/user/.m2/repository/repository.xml ----- - -Instead of using the URL, you can use the repository index as displayed by the `obr:url-list` command. -To do so, you have to use the `-i` option: - ----- -karaf@root()> obr:url-refresh -i 0 ----- - -=== `obr:url-remove` - -The `obr:url-remove` command removes an OBR repository from the OBR service. - -The `obr:url-remove` command expects the repository URL as argument: - ----- -karaf@root()> obr:url-remove file:/user/.m2/repository/repository.xml ----- - -Instead of using the URL, you can use the repository index as displayed by the `obr:url-list` command. -To do so, you have to use the `-i` option: - ----- -karaf@root()> obr:url-remove -i 0 ----- - -=== `obr:list` - -The `obr:list` command lists all bundles available on the registered OBR repositories: - ----- -karaf@root()> obr:list|more -Name | Symbolic Name | Version ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ -activemq-blueprint | org.apache.activemq.activemq-blueprint | 5.10.0.SNAPSHOT -activemq-camel | org.apache.activemq.activemq-camel | 5.10.0.SNAPSHOT -activemq-karaf | activemq-karaf | 5.10.0.SNAPSHOT -activemq-osgi | org.apache.activemq.activemq-osgi | 5.10.0.SNAPSHOT -Apache Aries Application API | org.apache.aries.application.api | 1.0.1.SNAPSHOT -... ----- - -=== `obr:info` - -The `obr:info` command displays the details about bundles available on the OBR service. Especially, it provides details about -capabilities and requirements of bundles. - -The `obr:info` command expects a bundle symbolic name as argument: - ----- -karaf@root()> obr:info org.apache.karaf.wrapper.core -------------------------------- -Apache Karaf :: Wrapper :: Core -------------------------------- -id: org.apache.karaf.wrapper.core/3.0.0 -description: Core implementation and integration of the Java Service Wrapper. It provides a complete integration of Karaf with your Operating System. -documentation: http://www.apache.org/ -symbolicname: org.apache.karaf.wrapper.core -presentationname: Apache Karaf :: Wrapper :: Core -license: http://www.apache.org/licenses/LICENSE-2.0.txt -uri: file:/user/.m2/repository/org/apache/karaf/wrapper/org.apache.karaf.wrapper.core/3.0.0/org.apache.karaf.wrapper.core-3.0.0.jar -size: 1281352 -version: 3.0.0 -Requires: - service:(&(service=org.apache.aries.blueprint.NamespaceHandler)(osgi.service.blueprint.namespace=http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0)) - package:(&(package=javax.management)) - package:(&(package=org.apache.karaf.wrapper)) - package:(&(package=org.apache.karaf.wrapper.management)) - package:(&(package=org.fusesource.jansi)(version>=1.11.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework)(version>=1.7.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework.launch)(version>=1.1.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework.startlevel)(version>=1.0.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.service.blueprint)(version>=1.0.0)(!(version>=2.0.0))) - package:(&(package=org.slf4j)(version>=1.7.0)(!(version>=2.0.0))) -Capabilities: - bundle:{manifestversion=2, symbolicname=org.apache.karaf.wrapper.core, presentationname=Apache Karaf :: Wrapper :: Core, version=3.0.0} - service:{service=org.apache.karaf.wrapper.WrapperService} - package:{package=org.apache.karaf.wrapper, version=3.0.0} - package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=3.0.0} ----- - -The `obr:info` command uses the following syntax to identify the bundles: `symbolic_name,version` where `version` is optional. -It means that you have to use the following command to see the info about the wrapper core bundle with version 3.0.0: - ----- -karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0 -... ----- - -You can specific multiple bundles separated by space: - ----- -karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0 -... ----- - -=== `obr:source` - -In addition of the bundles executable, the OBR service can also store the bundles sources. - -The `obr:source` command check the source URL in the OBR metadata for a given bundle, and download the sources on a target folder: - ----- -karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core ----- - -The `obr:source` command uses the following syntax to identify the bundles: `symbolic_name,version` where `version` is optional. -It means that you have to use the following command to download the source of wrapper core bundle with version 3.0.0: - ----- -karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0 ----- - -You can specify multiple bundles separated by space: - ----- -karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0 -... ----- - -=== `obr:resolve` - -The `obr:resolve` command displays the resolution output for a given set of requirements. Actually, it show the bundles providing -the capabilities to match the requirements. It's what the OBR service does when executing `obr:deploy`. - -Optionally, the `obr:resolve` command can deploy the bundles as the `obr:deploy` command does. - -For instance, to know the OBR bundle resolving the `org.apache.karaf.wrapper` package requirement, you can do: - ----- -karaf@root()> obr:resolve package=org.apache.karaf.wrapper -Required resource(s): ---------------------- - Apache Karaf :: Wrapper :: Core (3.0.0) ----- - -=== `obr:find` - -The `obr:find` command is similar to the `obr:resolve` one. It displays the bundles resolving the provided requirements, with details. - -For instance, to find the OBR bundle providing the `org.apache.karaf.wrapper` package, you can do: - ----- -karaf@root()> obr:find package=org.apache.karaf.wrapper -------------------------------- -Apache Karaf :: Wrapper :: Core -------------------------------- -id: org.apache.karaf.wrapper.core/3.0.0 -description: Core implementation and integration of the Java Service Wrapper. It provides a complete integration of Karaf with your Operating System. -documentation: http://www.apache.org/ -symbolicname: org.apache.karaf.wrapper.core -presentationname: Apache Karaf :: Wrapper :: Core -license: http://www.apache.org/licenses/LICENSE-2.0.txt -uri: file:/user/.m2/repository/org/apache/karaf/wrapper/org.apache.karaf.wrapper.core/3.0.0/org.apache.karaf.wrapper.core-3.0.0.jar -size: 1281352 -version: 3.0.0 -Requirements: - service:(&(service=org.apache.aries.blueprint.NamespaceHandler)(osgi.service.blueprint.namespace=http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0)) - package:(&(package=javax.management)) - package:(&(package=org.apache.karaf.wrapper)) - package:(&(package=org.apache.karaf.wrapper.management)) - package:(&(package=org.fusesource.jansi)(version>=1.11.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework)(version>=1.7.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework.launch)(version>=1.1.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.framework.startlevel)(version>=1.0.0)(!(version>=2.0.0))) - package:(&(package=org.osgi.service.blueprint)(version>=1.0.0)(!(version>=2.0.0))) - package:(&(package=org.slf4j)(version>=1.7.0)(!(version>=2.0.0))) -Capabilities: - bundle:{manifestversion=2, symbolicname=org.apache.karaf.wrapper.core, presentationname=Apache Karaf :: Wrapper :: Core, version=3.0.0} - service:{service=org.apache.karaf.wrapper.WrapperService} - package:{package=org.apache.karaf.wrapper, version=3.0.0} - package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=3.0.0} ----- - -=== `obr:deploy` - -The `obr:deploy` command installs a bundle from the OBR repository, including all bundles required to satisfy the bundle requirements. - ----- -karaf@root()> obr:deploy org.ops4j.pax.web.samples.helloworld-hs -Target resource(s): -------------------- - OPS4J Pax Web - Samples - Hello World - HttpService (4.0.0.SNAPSHOT) - -Required resource(s): ---------------------- - Apache ServiceMix :: Specs :: Activation API 1.4 (2.3.0.SNAPSHOT) - OPS4J Pax Web - Jetty Bundle (4.0.0.SNAPSHOT) - -Deploying...done. ----- - -By default, the bundles are just installed, not started. You can use the `-s` option to start the bundles. - -The `obr:deploy` command uses the following syntax to identify the bundles: `symbolic_name,version` where `version` is optional. -It means that you have to use the following command to deploy the wrapper core bundle with version 3.0.0: - ----- -karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0 ----- - -You can specify multiple bundles separated by space: - ----- -karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0 -... ----- - -== `obr:start` - -The `obr:start` command does the same as `obr:deploy -s` command. It installs the bundle (and all required bundles to -satisfy the requirements) and starts all installed bundles. - ----- -karaf@root()> obr:start org.ops4j.pax.web.samples.helloworld-hs -Target resource(s): -------------------- - OPS4J Pax Web - Samples - Hello World - HttpService (4.0.0.SNAPSHOT) - -Required resource(s): ---------------------- - Apache ServiceMix :: Specs :: Activation API 1.4 (2.3.0.SNAPSHOT) - OPS4J Pax Web - Jetty Bundle (4.0.0.SNAPSHOT) - -Deploying...done. ----- - -The `obr:start` command uses the following syntax to identify the bundles: `symbolic_name,version` where `version` is optional. -It means that you have to use the following command to deploy and start the wrapper core bundle with version 3.0.0: - ----- -karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0 ----- - -You can specify multiple bundles separated by space: - ----- -karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0 -... ----- - -== JMX ObrMBean - -On the JMX layer, Apache Karaf provides a MBean dedicated to the management of the OBR service: the ObrMBean. - -The ObjectName to use is `org.apache.karaf:type=obr,name=*`. - -=== Attributes - -The `Urls` attribute provides the list of registered OBR repositories URLs. - -The `Bundles` attribute provides a tabular data containing all bundles available on the registered OBR repositories. - -=== Operations - -* `addUrl(url)` registers the OBR repository using the `url` to the `repository.xml`. -* `removeUrl(url)` removes the OBR repository at the given `url`. -* `refreshUrl(url)` refreshes the OBR repository at the given `url`. -* `deployBundle(name)` deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service. The bundles are not automatically started. -* `deployBundle(name, start, deployOptional)` deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service. - If `start` is `true`, the bundles are automatically started. If `deployOptional` is `true`, even the optional requirements will be resolved - by the OBR service (meaning installing more bundles to satisfy the optional requirements). - -The name to identify a bundle uses the following syntax: `symbolic_name,version` where version is optional. - -== Apache Karaf Cave - -In addition of being an OBR client, Apache Karaf can act as an OBR repositories server, thanks to Apache Karaf Cave. - -See the [Apache Karaf Cave sub-project|http://karaf.apache.org/index/subprojects/cave.html] for details. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/provisioning-schema.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/provisioning-schema.adoc b/manual/src/main/asciidoc/users-guide/provisioning-schema.adoc deleted file mode 100644 index 41af73a..0000000 --- a/manual/src/main/asciidoc/users-guide/provisioning-schema.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// -// 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. -// - -= Features XML Schemas (provisioning) - -Apache Karaf 3.0.0 supports different versions of the features XML schemas. - -The features XML schema can be found directly in the Apache Karaf sources, in the `features/core` module: - ----- -features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.2.0.xsd -features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.1.0.xsd -features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.0.0.xsd ----- - -These schemas are also available on the Apache Karaf website: - -* [http://karaf.apache.org/xmlns/features/v1.2.0] -* [http://karaf.apache.org/xmlns/features/v1.1.0] -* [http://karaf.apache.org/xmlns/features/v1.0.0] - -== karaf-features-1.2.0.xsd - -{snippet:url=../features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.2.0.xsd|lang=xml|pygmentize=true} -{snippet} - -== karaf-features-1.1.0.xsd - -{snippet:url=../features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.1.0.xsd|lang=xml|pygmentize=true} -{snippet} - -== karaf-features-1.0.0.xsd - -{snippet:url=../features/core/src/main/resources/org/apache/karaf/features/karaf-features-1.0.0.xsd|lang=xml|pygmentize=true} -{snippet} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/remote.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/remote.adoc b/manual/src/main/asciidoc/users-guide/remote.adoc deleted file mode 100644 index 05fe439..0000000 --- a/manual/src/main/asciidoc/users-guide/remote.adoc +++ /dev/null @@ -1,423 +0,0 @@ -// -// 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. -// - -= Remote - -Apache Karaf supports a complete remote mechanism allowing you to remotely connect to a running Apache Karaf instance. -More over, you can also browse, download, and upload files remotely to a running Apache Karaf instance. - -Apache Karaf embeds a complete SSHd server. - -== SSHd server - -When you start Apache Karaf, it enables a remote console that can be accessed over SSH. - -This remote console provides all the features of the "local" console, and gives a remote user complete control over the -container and services running inside of it. As the "local" console, the remote console is secured by a RBAC mechanism -(see the [Security section|security] of the user guide for details). - -In addition of the remote console, Apache Karaf also provides a remote filesystem. This remote filesystem can be accessed -using a SCP/SFTP client. - -=== Configuration - -The configuration of the SSHd server is stored in the `etc/org.apache.karaf.shell.cfg` 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. -# -################################################################################ - -# -# These properties are used to configure Karaf's ssh shell. -# - -# -# Via sshPort and sshHost you define the address you can login into Karaf. -# -sshPort = 8101 -sshHost = 0.0.0.0 - -# -# The sshIdleTimeout defines the inactivity timeout to logout the SSH session. -# The sshIdleTimeout is in milliseconds, and the default is set to 30 minutes. -# -sshIdleTimeout = 1800000 - -# -# sshRealm defines which JAAS domain to use for password authentication. -# -sshRealm = karaf - -# -# The location of the hostKey file defines where the private/public key of the server -# is located. If no file is at the defined location it will be ignored. -# -hostKey = ${karaf.etc}/host.key - -# -# Role name used for SSH access authorization -# If not set, this defaults to the ${karaf.admin.role} configured in etc/system.properties -# -# sshRole = admin - -# -# Self defined key size in 1024, 2048, 3072, or 4096 -# If not set, this defaults to 1024. -# -# keySize = 1024 - -# -# Specify host key algorithm, defaults to DSA -# -# algorithm = DSA - -# -# Defines the completion mode on the Karaf shell console. The possible values are: -# - GLOBAL: it's the same behavior as in previous Karaf releases. The completion displays all commands and all aliases -# ignoring if you are in a subshell or not. -# - FIRST: the completion displays all commands and all aliases only when you are not in a subshell. When you are -# in a subshell, the completion displays only the commands local to the subshell. -# - SUBSHELL: the completion displays only the subshells on the root level. When you are in a subshell, the completion -# displays only the commands local to the subshell. -# This property define the default value when you use the Karaf shell console. -# You can change the completion mode directly in the shell console, using shell:completion command. -# -completionMode = GLOBAL ----- - -The `etc/org.apache.karaf.shell.cfg` configuration file contains different properties to configure the SSHd server: - -* `sshPort` is the port number where the SSHd server is bound (by default, it's 8101). -* `sshHost` is the address of the network interface where the SSHd server is bound. The default value is 0.0.0.0, - meaning that the SSHd server is bound on all network interfaces. You can bind on a target interface providing the IP - address of the network interface. -* `hostKey` is the location of the `host.key` file. By defaut, it uses `etc/host.key`. This file stores the public - and private key pair of the SSHd server. -* `sshRole` is the default role used for SSH access. The default value is the value of `karaf.admin.role` property - defined in `etc/system.properties`. See the [Security section|security] of this user guide for details. -* `keySize` is the key size used by the SSHd server. The possible values are 1024, 2048, 3072, or 4096. The default - value is 1024. -* `algorithm` is the host key algorithm used by the SSHd server. The possible values are DSA or RSA. The default - value is DSA. - -The SSHd server configuration can be changed at runtime: - -* by editing the `etc/org.apache.karaf.shell.cfg` configuration file -* by using the `config:*` commands - -At runtime, when you change the SSHd server configuration, you have to restart the SSHd server to load the changes. -You can do it with: - ----- -karaf@root()> bundle:restart -f org.apache.karaf.shell.ssh ----- - -The Apache Karaf SSHd server supports key/agent authentication and password authentication. - -=== Console clients - -h4. System native clients - -The Apache Karaf SSHd server is a pure SSHd server, similar to OpenSSH daemon. - -It means that you can use directly a SSH client from your system. - -For instance, on Unix, you can directly use OpenSSH: - ----- -~$ ssh -p 8101 karaf@localhost -Authenticated with partial success. -Authenticated with partial success. -Authenticated with partial success. -Password authentication -Password: - __ __ ____ - / //_/____ __________ _/ __/ - / ,< / __ `/ ___/ __ `/ /_ - / /| |/ /_/ / / / /_/ / __/ - /_/ |_|\__,_/_/ \__,_/_/ - - Apache Karaf (3.0.0) - -Hit '<tab>' for a list of available commands -and '[cmd] --help' for help on a specific command. -Hit 'system:shutdown' to shutdown Karaf. -Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session. - -karaf@root()> ----- - -On Windows, you can use Putty, Kitty, etc. - -If you don't have SSH client installed on your machine, you can use Apache Karaf client. - -h4. `ssh:ssh` command - -Apache Karaf itself provides a SSH client. When you are on the Apache Karaf console, you have the `ssh:ssh` command: - ----- -karaf@root()> ssh:ssh --help -DESCRIPTION - ssh:ssh - - Connects to a remote SSH server - -SYNTAX - ssh:ssh [options] hostname [command] - -ARGUMENTS - hostname - The host name to connect to via SSH - command - Optional command to execute - -OPTIONS - --help - Display this help message - -p, --port - The port to use for SSH connection - (defaults to 22) - -P, --password - The password for remote login - -q - Quiet Mode. Do not ask for confirmations - -l, --username - The user name for remote login - ----- - -Thanks to the `ssh:ssh` command, you can connect to another running Apache Karaf instance: - ----- -karaf@root()> ssh:ssh -p 8101 [email protected] -Connecting to host 192.168.134.2 on port 8101 -Connecting to unknown server. Add this server to known hosts ? (y/n) -Storing the server key in known_hosts. -Connected - __ __ ____ - / //_/____ __________ _/ __/ - / ,< / __ `/ ___/ __ `/ /_ - / /| |/ /_/ / / / /_/ / __/ - /_/ |_|\__,_/_/ \__,_/_/ - - Apache Karaf (3.0.0) - -Hit '<tab>' for a list of available commands -and '[cmd] --help' for help on a specific command. -Hit 'system:shutdown' to shutdown Karaf. -Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session. - -karaf@root()> ----- - -When you don't provide the `command` argument to the `ssh:ssh` command, you are in the interactive mode: you have -a complete remote console available, where you can type commands, etc. - -You can also provide directly a command to execute using the `command` argument. For instance, to remotely shutdown -a Apache Karaf instance: - ----- -karaf@root()> ssh:ssh -p 8101 karaf@localhost system:shutdown -f -Connecting to host localhost on port 8101 -Connected ----- - -As the `ssh:ssh` command is a pure SSH client, so it means that you can connect to a Unix OpenSSH daemon: - ----- -karaf@root()> ssh:ssh user@localhost -Connecting to host localhost on port 22 -Connecting to unknown server. Add this server to known hosts ? (y/n) -Storing the server key in known_hosts. -Agent authentication failed, falling back to password authentication. -Password: Connected -Last login: Sun Sep 8 19:21:12 2013 -user@server:~$ ----- - -h4. Apache Karaf client - -The `ssh:ssh` command requires to be run into a running Apache Karaf console. - -For commodity, the `ssh:ssh` command is "wrapped" as a standalone client: the `bin/client` Unix script (`bin\client.bat` on Windows). - ----- -bin/client --help -Apache Karaf client - -a [port] specify the port to connect to - -h [host] specify the host to connect to - -u [user] specify the user name - --help shows this help message - -v raise verbosity - -r [attempts] retry connection establishment (up to attempts times) - -d [delay] intra-retry delay (defaults to 2 seconds) - -b batch mode, specify multiple commands via standard input - -f [file] read commands from the specified file - [commands] commands to run -If no commands are specified, the client will be put in an interactive mode ----- - -For instance, to connect to local Apache Karaf instance (on the default SSHd server 8101 port), you can directly use -`bin/client` Unix script (`bin\client.bat` on Windows) without any argument or option: - ----- -bin/client -Logging in as karaf -343 [pool-2-thread-4] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key: - __ __ ____ - / //_/____ __________ _/ __/ - / ,< / __ `/ ___/ __ `/ /_ - / /| |/ /_/ / / / /_/ / __/ - /_/ |_|\__,_/_/ \__,_/_/ - - Apache Karaf (3.0.0) - -Hit '<tab>' for a list of available commands -and '[cmd] --help' for help on a specific command. -Hit 'system:shutdown' to shutdown Karaf. -Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session. - -karaf@root()> ----- - -When you don't provide the `command` argument to the `bin/client` Unix script (`bin\client.bat` on Windows), you are -in the interactive mode: you have a complete remote console available, where you can type commands, etc. - -You can also provide directly a command to execute using the `command` argument. For instance, to remotely shutdown -a Apache Karaf instance: - ----- -bin/client "system:shutdown -f" -Logging in as karaf -330 [pool-2-thread-3] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key: ----- - -As the Apache Karaf client is a pure SSH client, you can use to connect to any SSHd daemon (like Unix OpenSSH daemon): - ----- -bin/client -a 22 -h localhost -u user -Logging in as user -353 [pool-2-thread-2] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at localhost/127.0.0.1:22 presented unverified key: -Password: -Welcome to Ubuntu 13.10 (GNU/Linux 3.11.0-13-generic x86_64) - - * Documentation: https://help.ubuntu.com/ - -Last login: Tue Dec 3 18:18:31 2013 from localhost ----- - -h4. Logout - -When you are connected to a remote Apache Karaf console, you can logout using: - -* using CTRL-D key binding. Note that CTRL-D just logout from the remote console in this case, it doesn't shutdown - the Apache Karaf instance (as CTRL-D does when used on a local console). -* using `shell:logout` command (or simply `logout`) - -=== Filsystem clients - -Apache Karaf SSHd server also provides complete fileystem access via SSH. For security reason, the available filesystem -is limited to `KARAF_BASE` directory. - -You can use this remote filesystem with any SCP/SFTP compliant clients. - -h4. Native SCP/SFTP clients - -On Unix, you can directly use `scp` command to download/upload files to the Apache Karaf filesystem. For instance, -to retrieve the `karaf.log` file remotely: - ----- -~$ scp -P 8101 karaf@localhost:/data/log/karaf.log . -Authenticated with partial success. -Authenticated with partial success. -Authenticated with partial success. -Password authentication -Password: -karaf.log ----- - -As you have access to the complete `KARAF_BASE` directory, you can remotely change the configuration file in the `etc` -folder, retrieve log files, populate the `system` folder. - -On Windows, you can use WinSCP to access the Apache Karaf filesystem. - -It's probably easier to use a SFTP complient client. - -For instance, on Unix system, you can use `lftp` or `ncftp`: - ----- -$ lftp -lftp :~> open -u karaf sftp://localhost:8101 -Password: -lftp karaf@localhost:~> ls --rw-r--r-- 1 jbonofre jbonofre 27754 Oct 26 10:50 LICENSE --rw-r--r-- 1 jbonofre jbonofre 1919 Dec 3 05:34 NOTICE --rw-r--r-- 1 jbonofre jbonofre 3933 Aug 18 2012 README --rw-r--r-- 1 jbonofre jbonofre 101041 Dec 3 05:34 RELEASE-NOTES -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 bin -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 18:57 data -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 demos -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 13:02 deploy -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 17:59 etc -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 13:02 instances -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 13:02 lib --rw-r--r-- 1 jbonofre jbonofre 0 Dec 3 13:02 lock -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 system -lftp karaf@localhost:/> ----- - -You can also use graphic client like `filezilla`, `gftp`, `nautilus`, etc. - -On Windows, you can use `filezilla`, `WinSCP`, etc. - -h4. Apache Maven - -Apache Karaf `system` folder is the Karaf repository, that use a Maven directory structure. It's where Apache Karaf -looks for the artifacts (bundles, features, kars, etc). - -Using Apache Maven, you can populate the `system` folder using the `deploy:deploy-file` goal. - -For instance, you want to add the Apache ServiceMix facebook4j OSGi bundle, you can do: - ----- -mvn deploy:deploy-file -Dfile=org.apache.servicemix.bundles.facebook4j-2.0.2_1.jar -DgroupId=org.apache.servicemix.bundles -DartifactId=org.apache.servicemix.bundles.facebook4j -Dversion=2.0.2_1 -Dpackaging=jar -Durl=scp://localhost:8101/system ----- - -{tip} -If you want to turn Apache Karaf as a simple Maven repository, you can use [Apache Karaf Cave|http://karaf.apache.org/index/subprojects/cave.html]. -{tip} - -== JMX MBeanServer - -Apache Karaf provides a JMX MBeanServer. - -This MBeanServer is available remotely, using any JMX client like `jconsole`. - -You can find details on the [Monitoring section|monitoring] of the user guide. \ No newline at end of file
