http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/security.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/security.adoc b/manual/src/main/asciidoc/user-guide/security.adoc new file mode 100644 index 0000000..afeba11 --- /dev/null +++ b/manual/src/main/asciidoc/user-guide/security.adoc @@ -0,0 +1,584 @@ +// +// 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. +// + +=== Security + +Apache Karaf provides an advanced and flexible security system, powered by JAAS (Java Authentication and Authorization +Service) in an OSGi compliant way. + +It provides a dynamic security system. + +The Apache Karaf security framework is used internally to control the access to: + +* the OSGi services (described in the developer guide) +* the console commands +* the JMX layer +* the WebConsole + +Your applications can also use the security framework (see the developer guide for details). + +==== Realms + +Apache Karaf is able to manage multiple realms. A realm contains the definition of the login modules to use for the +authentication and/or authorization on this realm. The login modules define the authentication and authorization for +the realm. + +The `jaas:realm-list` command list the current defined realms: + +---- +karaf@root()> jaas:realm-list +Index | Realm Name | Login Module Class Name +----------------------------------------------------------------------------------- +1 | karaf | org.apache.karaf.jaas.modules.properties.PropertiesLoginModule +2 | karaf | org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule +---- + +You can see that the Apache Karaf provides a default realm named `karaf`. + +This realm has two login modules: + +* the `PropertiesLoginModule` uses the `etc/users.properties` file as backend for users, groups, roles and password. + This login module authenticates the users and returns the users' roles. +* the `PublickeyLoginModule` is especially used by the SSHd. It uses the `etc/keys.properties` file. This file contains + the users and a public key associated to each user. + +Apache Karaf provides additional login modules (see the developer guide for details): + +* JDBCLoginModule uses a database as backend +* LDAPLoginModule uses a LDAP server as backend +* SyncopeLoginModule uses Apache Syncope as backend +* OsgiConfigLoginModule uses a configuration as backend + +You can manage an existing realm, login module, or create your own realm using the `jaas:realm-manage` command. + +==== Users, groups, roles, and passwords + +As we saw, by default, Apache Karaf uses a PropertiesLoginModule. + +This login module uses the `etc/users.properties` file as storage for the users, groups, roles and passwords. + +The initial `etc/users.properties` file contains: + +---- +################################################################################ +# +# 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. +# +################################################################################ + +# +# This file contains the users, groups, and roles. +# Each line has to be of the format: +# +# USER=PASSWORD,ROLE1,ROLE2,... +# USER=PASSWORD,_g_:GROUP,... +# _g_\:GROUP=ROLE1,ROLE2,... +# +# All users, grousp, and roles entered in this file are available after Karaf startup +# and modifiable via the JAAS command group. These users reside in a JAAS domain +# with the name "karaf". +# +karaf = karaf,_g_:admingroup +_g_\:admingroup = group,admin,manager,viewer +---- + +We can see in this file, that we have one user by default: `karaf`. +The default password is `karaf`. + +The `karaf` user is member of one group: the `admingroup`. + +A group is always prefixed by `_g_:`. An entry without this prefix is an user. + +A group defines a set of roles. By default, the `admingroup` defines `group`, `admin`, `manager`, and `viewer` +roles. + +It means that the `karaf` user will have the roles defined by the `admingroup`. + +===== Commands + +The `jaas:*` commands manage the realms, users, groups, roles in the console. + +====== `jaas:realm-list` + +We already used the `jaas:realm-list` previously in this section. + +The `jaas:realm-list` command list the realm and the login modules for each realm: + +---- +karaf@root()> jaas:realm-list +Index | Realm Name | Login Module Class Name +----------------------------------------------------------------------------------- +1 | karaf | org.apache.karaf.jaas.modules.properties.PropertiesLoginModule +2 | karaf | org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule +---- + +We have here one realm (`karaf`) containing two login modules (`PropertiesLoginModule` and `PublickeyLoginModule`). + +The `index` is used by the `jaas:realm-manage` command to easily identify the realm/login module that we want to manage. + +====== `jaas:realm-manage` + +The `jaas:realm-manage` command switch in realm/login module edit mode, where you can manage the users, groups, and roles in the login module. + +To identify the realm and login module that you want to manage, you can use the `--index` option. +The indexes are displayed by the `jaas:realm-list` command: + +---- +karaf@root()> jaas:realm-manage --index 1 +---- + +Another way is to use the `--realm` and `--module` options. The `--realm` option expects the realm name, and the `--module` +option expects the login module class name: + +---- +karaf@root()> jaas:realm-manage --realm karaf --module org.apache.karaf.jaas.modules.properties.PropertiesLoginModule +---- + +====== `jaas:user-list` + +When you are in edit mode, you can list the users in the login module using the `jaas:user-list`: + +---- +karaf@root()> jaas:user-list +User Name | Group | Role +-------------------------------- +karaf | admingroup | admin +karaf | admingroup | manager +karaf | admingroup | viewer +---- + +You can see the user name and the group by role. + +====== `jaas:user-add` + +The `jaas:user-add` command adds a new user (and the password) in the currently edited login module: + +---- +karaf@root()> jaas:user-add foo bar +---- + +To "commit" your change (here the user addition), you have to execute the `jaas:update` command: + +---- +karaf@root()> jaas:update +karaf@root()> jaas:realm-manage --index 1 +karaf@root()> jaas:user-list +User Name | Group | Role +-------------------------------- +karaf | admingroup | admin +karaf | admingroup | manager +karaf | admingroup | viewer +foo | | +---- + +On the other hand, if you want to rollback the user addition, you can use the `jaas:cancel` command. + +====== `jaas:user-delete` + +The `jaas:user-delete` command deletes an user from the currently edited login module: + +---- +karaf@root()> jaas:user-delete foo +---- + +Like for the `jaas:user-add` command, you have to use the `jaas:update` to commit your change (or `jaas:cancel` to rollback): + +---- +karaf@root()> jaas:update +karaf@root()> jaas:realm-manage --index 1 +karaf@root()> jaas:user-list +User Name | Group | Role +-------------------------------- +karaf | admingroup | admin +karaf | admingroup | manager +karaf | admingroup | viewer +---- + +====== `jaas:group-add` + +The `jaas:group-add` command assigns a group (and eventually creates the group) to an user in the currently edited login module: + +---- +karaf@root()> jaas:group-add karaf mygroup +---- + +====== `jaas:group-delete` + +The `jaas:group-delete` command removes an user from a group in the currently edited login module: + +---- +karaf@root()> jaas:group-delete karaf mygroup +---- + +====== `jaas:group-role-add` + +The `jaas:group-role-add` command adds a role in a group in the currently edited login module: + +---- +karaf@root()> jaas:group-role-add mygroup myrole +---- + +====== `jaas:group-role-delete` + +The `jaas:group-role-delete` command removes a role from a group in the currently edited login module: + +---- +karaf@root()> jaas:group-role-delete mygroup myrole +---- + +====== `jaas:update` + +The `jaas:update` command commits your changes in the login module backend. For instance, in the case of the PropertiesLoginModule, +the `etc/users.properties` will be updated only after the execution of the `jaas:update` command. + +====== `jaas:cancel` + +The `jaas:cancel` command rollback your changes and doesn't update the login module backend. + +==== Passwords encryption + +By default, the passwords are stored in clear form in the `etc/users.properties` file. + +It's possible to enable encryption in the `etc/org.apache.karaf.jaas.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. +# +################################################################################ + +# +# Boolean enabling / disabling encrypted passwords +# +encryption.enabled = false + +# +# Encryption Service name +# the default one is 'basic' +# a more powerful one named 'jasypt' is available +# when installing the encryption feature +# +encryption.name = + +# +# Encryption prefix +# +encryption.prefix = {CRYPT} + +# +# Encryption suffix +# +encryption.suffix = {CRYPT} + +# +# Set the encryption algorithm to use in Karaf JAAS login module +# Supported encryption algorithms follow: +# MD2 +# MD5 +# SHA-1 +# SHA-256 +# SHA-384 +# SHA-512 +# +encryption.algorithm = MD5 + +# +# Encoding of the encrypted password. +# Can be: +# hexadecimal +# base64 +# +encryption.encoding = hexadecimal +---- + +If the `encryption.enabled` property is set to true, the password encryption is enabled. + +With encryption enabled, the password are encrypted at the first time an user logs in. The encrypted passwords are +prefixed and suffixed with `\{CRYPT\`}. To re-encrypt the password, you can reset the password in clear (in `etc/users.properties` +file), without the `\{CRYPT\`} prefix and suffix. Apache Karaf will detect that this password is in clear (because it's not +prefixed and suffixed with `\{CRYPT\`}) and encrypt it again. + +The `etc/org.apache.karaf.jaas.cfg` configuration file allows you to define advanced encryption behaviours: + +* the `encryption.prefix` property defines the prefix to "flag" a password as encrypted. The default is `\{CRYPT\`}. +* the `encryption.suffix` property defines the suffix to "flag" a password as encrypted. The default is `\{CRYPT\`}. +* the `encryption.algorithm` property defines the algorithm to use for encryption (digest). The possible values are `MD2`, `MD5`, +`SHA-1`, `SHA-256`, `SHA-384`, `SHA-512`. The default is `MD5`. +* the `encryption.encoding` property defines the encoding of the encrypted password. The possible values are `hexadecimal` + or `base64`. The default value is `hexadecimal`. + +==== Managing authentication by key + +For the SSH layer, Karaf supports the authentication by key, allowing to login without providing the password. + +The SSH client (so bin/client provided by Karaf itself, or any ssh client like OpenSSH) uses a public/private keys pair that +will identify himself on Karaf SSHD (server side). + +The keys allowed to connect are stored in `etc/keys.properties` file, following the format: + +---- +user=key,role +---- + +By default, Karaf allows a key for the karaf user: + +---- +# karaf=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCXYFCPFSMLzLKSuYKi64QL8Fgc9QAAAIEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACBAKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53JjTuyk31drV2qxhIOsLDC9dGCWj47Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,admin +---- + +[NOTE] +==== +For security reason, this key is disabled. We encourage to create the keys pair per client and update the `etc/keys.properties` file. +==== + +The easiest way to create key pair is to use OpenSSH. + +You can create a key pair using: + +---- +ssh-keygen -t dsa -f karaf.id_dsa -N karaf +---- + +You have now the public and private keys: + +---- +-rw------- 1 jbonofre jbonofre 771 Jul 25 22:05 karaf.id_dsa +-rw-r--r-- 1 jbonofre jbonofre 607 Jul 25 22:05 karaf.id_dsa.pub +---- + +You can copy in the content of the `karaf.id_dsa.pub` file in the `etc/keys.properties`: + +---- +karaf=AAAAB3NzaC1kc3MAAACBAJLj9vnEhu3/Q9Cvym2jRDaNWkATgQiHZxmErCmiLRuD5Klfv+HT/+8WoYdnvj0YaXFP80phYhzZ7fbIO2LRFhYhPmGLa9nSeOsQlFuX5A9kY1120yB2kxSIZI0fU2hy1UCgmTxdTQPSYtdWBJyvO/vczoX/8I3FziEfss07Hj1NAAAAFQD1dKEzkt4e7rBPDokPOMZigBh4kwAAAIEAiLnpbGNbKm8SNLUEc/fJFswg4G4VjjngjbPZAjhkYe4+H2uYmynry6V+GOTS2kaFQGZRf9XhSpSwfdxKtx7vCCaoH9bZ6S5Pe0voWmeBhJXi/Sww8f2stpitW2Oq7V7lDdDG81+N/D7/rKDD5PjUyMsVqc1n9wCTmfqmi6XPEw8AAACAHAGwPn/Mv7P9Q9+JZRWtGq+i4pL1zs1OluiStCN9e/Ok96t3gRVKPheQ6IwLacNjC9KkSKrLtsVyepGA+V5j/N+Cmsl6csZilnLvMUTvL/cmHDEEhTIQnPNrDDv+tED2BFqkajQqYLgMWeGVqXsBU6IT66itZlYtrq4v6uDQG/o=,admin +---- + +and specify to the client to use the `karaf.id_dsa` private key: + +---- +bin/client -k ~/karaf.id_dsa +---- + +or to ssh + +---- +ssh -p 8101 -i ~/karaf.id_dsa karaf@localhost +---- + +==== RBAC + +Apache Karaf uses the roles to control the access to the resources: it's a RBAC (Role Based Access Control) system. + +The roles are used to control: + +* access to OSGi services +* access to the console (control the execution of the commands) +* access to JMX (MBeans and/or operations) +* access to the WebConsole + +===== OSGi services + +The details about OSGi services RBAC support is explained in the developer guide. + +===== Console + +Console RBAC supports is a specialization of the OSGi service RBAC. Actually, in Apache Karaf, all console commands are +defined as OSGi services. + +The console command name follows the `scope:name` format. + +The ACL (Access Lists) are defined in `etc/org.apache.karaf.command.acl.<scope>.cfg` configuration files, where `<scope>` +is the commands scope. + +For instance, we can define the ACL to the `feature:*` commands by creating a `etc/org.apache.karaf.command.acl.feature.cfg` +configuration file. In this `etc/org.apache.karaf.command.acl.feature.cfg` configuration file, we can set: + +---- +list = viewer +info = viewer +install = admin +uninstall = admin +---- + +Here, we define that `feature:list` and `feature:info` commands can be executed by users with `viewer` role, whereas +the `feature:install` and `feature:uninstall` commands can only be executed by users with `admin` role. +Note that users in the admin group will also have viewer role, so will be able to do everything. + +Apache Karaf command ACLs can control access using (inside a given command scope): + +* the command name regex (e.g. `name = role`) +* the command name and options or arguments values regex (e.g. `name[/.*[0-9][0-9][0-9]+.*/] = role` to execute name only with argument value above 100) + +Both command name and options/arguments support exact matching or regex matching. + +By default, Apache Karaf defines the following commands ACLs: + +* `etc/org.apache.karaf.command.acl.bundle.cfg` configuration file defines the ACL for `bundle:*` commands. + This ACL limits the execution of `bundle:*` commands for system bundles only to the users with `admin` role, whereas + `bundle:*` commands for non-system bundles can be executed by the users with `manager` role. +* `etc/org.apache.karaf.command.acl.config.cfg` configuration file defines the ACL for `config:*` commands. + This ACL limits the execution of `config:*` commands with `jmx.acl.*`, `org.apache.karaf.command.acl.*`, and + `org.apache.karaf.service.acl.*` configuration PID to the users with `admin` role. For the other configuration PID, + the users with the `manager` role can execute `config:*` commands. +* `etc/org.apache.karaf.command.acl.feature.cfg` configuration file defines the ACL for `feature:*` commands. + Only the users with `admin` role can execute `feature:install` and `feature:uninstall` commands. The other `feature:*` + commands can be executed by any user. +* `etc/org.apache.karaf.command.acl.jaas.cfg` configuration file defines the ACL for `jaas:*` commands. + Only the users with `admin` role can execute `jaas:update` command. The other `jaas:*` commands can be executed by any + user. +* `etc/org.apache.karaf.command.acl.kar.cfg` configuration file defines the ACL for `kar:*` commands. + Only the users with `admin` role can execute `kar:install` and `kar:uninstall` commands. The other `kar:*` commands + can be executed by any user. +* `etc/org.apache.karaf.command.acl.shell.cfg` configuration file defines the ACL for `shell:*` and "direct" commands. + Only the users with `admin` role can execute `shell:edit`, `shell:exec`, `shell:new`, and `shell:java` commands. + The other `shell:*` commands can be executed by any user. + +You can change these default ACLs, and add your own ACLs for additional command scopes (for instance `etc/org.apache.karaf.command.acl.cluster.cfg` for +Apache Karaf Cellar, `etc/org.apache.karaf.command.acl.camel.cfg` from Apache Camel, ...). + +You can fine tuned the command RBAC support by editing the `karaf.secured.services` property in `etc/system.properties`: + +---- +# +# By default, only Karaf shell commands are secured, but additional services can be +# secured by expanding this filter +# +karaf.secured.services = (&(osgi.command.scope=*)(osgi.command.function=*)) +---- + +===== JMX + +Like for the console commands, you can define ACL (AccessLists) to the JMX layer. + +The JMX ACL are defined in `etc/jmx.acl<ObjectName>.cfg` configuration file, where `<ObjectName>` is a MBean object name +(for instance `org.apache.karaf.bundle` represents `org.apache.karaf;type=Bundle` MBean). + +The `etc/jmx.acl.cfg` is the most generic configuration file and is used when no specific ones are found. +It contains the "global" ACL definition. + +JMX ACLs can control access using (inside a JMX MBean): + +* the operation name regex (e.g. `operation* = role`) +* the operation arguments value regex (e.g. `operation(java.lang.String, int)[/([1-4])?[0-9]/,/.*/] = role`) + +By default, Apache Karaf defines the following JMX ACLs: + +* `etc/jmx.acl.org.apache.karaf.bundle.cfg` configuration file defines the ACL for the `org.apache.karaf:type=bundle` + MBean. This ACL limits the `setStartLevel()`, `start()`, `stop()`, and `update()` operations for system bundles for + only users with `admin` role. The other operations can be performed by users with the `manager` role. +* `etc/jmx.acl.org.apache.karaf.config.cfg` configuration file defines the ACL for the `org.apache.karaf:type=config` + MBean. This ACL limits the change on `jmx.acl*`, `org.apache.karaf.command.acl*`, and `org.apache.karaf.service.acl*` + configuration PIDs for only users with `admin` role. The other operations can be performed by users with the `manager` role. +* `etc/jmx.acl.org.apache.karaf.security.jmx.cfg` configuration file defines the ACL for the `org.apache.karaf:type=security,area=jmx` + MBean. This ACL limits the invocation of the `canInvoke()` operation for the users with `viewer` role. +* `etc/jmx.acl.osgi.compendium.cm.cfg` configuration file defines the ACL for the `osgi.compendium:type=cm` MBean. + This ACL limits the changes on `jmx.acl*`, `org.apache.karaf.command.acl*`, and `org.apache.karaf.service.acl*` + configuration PIDs for only users with `admin` role. The other operations can be performed by users with the `manager` role. +* `etc/jmx.acl.java.lang.Memory.cfg` configuration file defines the ACL for the core JVM Memory MBean. + This ACL limits the invocation of the `gc` operation for only users with the `manager` role. +* `etc/jmx.acl.cfg` configuration file is the most generic file. The ACLs defined here are used when no other specific + ACLs match (by specific ACL, it's an ACL defined in another MBean specific `etc/jmx.acl.*.cfg` configuration file). + The `list*()`, `get*()`, `is*()` operations can be performed by users with the `viewer` role. + The `set*()` and all other `*()` operations can be performed by users with the `admin` role. + +===== WebConsole + +The Apache Karaf WebConsole is not available by default. To enable it, you have to install the `webconsole` feature: + +---- +karaf@root()> feature:install webconsole +---- + +The WebConsole doesn't support fine grained RBAC like console or JMX for now. + +All users with the `admin` role can logon the WebConsole and perform any operations. + +==== SecurityMBean + +Apache Karaf provides a JMX MBean to check if the current user can invoke a given MBean and/or operation. + +The `canInvoke()` operation gets the roles of the current user, and check if one the roles can invoke the MBean and/or the +operation, eventually with a given argument value. + +===== Operations + +* `canInvoke(objectName)` returns `true` if the current user can invoke the MBean with the `objectName`, `false` else. +* `canInvoke(objectName, methodName)` returns `true` if the current user can invoke the operation `methodName` on the MBean + with the `objectName`, `false` else. +* `canInvoke(objectName, methodName, argumentTypes)` returns `true` if the current user can invoke the operation `methodName` +with the array of arguments types `argumentTypes` on the MBean with `objectName`, `false` else. +* `canInvoke(bulkQuery)` returns a tabular data containing for each operation in the `bulkQuery` tabular data if `canInvoke` +is `true` or `false`. + +==== Security providers + +Some applications require specific security providers to be available, such as [BouncyCastle|http://www.bouncycastle.org]. + +The JVM imposes some restrictions about the use of such jars: they have to be signed and be available on the boot classpath. + +One way to deploy those providers is to put them in the JRE folder at `$JAVA_HOME/jre/lib/ext` and modify the security +policy configuration (`$JAVA_HOME/jre/lib/security/java.security`) in order to register such providers. + +While this approach works fine, it has a global effect and requires you to configure all your servers accordingly. + +Apache Karaf offers a simple way to configure additional security providers: +* put your provider jar in `lib/ext` +* modify the `etc/config.properties` configuration file to add the following property + +---- +org.apache.karaf.security.providers = xxx,yyy +---- + +The value of this property is a comma separated list of the provider class names to register. + +For instance, to add the bouncycastle security provider, you define: + +---- +org.apache.karaf.security.providers = org.bouncycastle.jce.provider.BouncyCastleProvider +---- + +In addition, you may want to provide access to the classes from those providers from the system bundle so that all bundles +can access those. + +It can be done by modifying the `org.osgi.framework.bootdelegation` property in the same configuration file: + +---- +org.osgi.framework.bootdelegation = ...,org.bouncycastle* +----
http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/start-stop.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/start-stop.adoc b/manual/src/main/asciidoc/user-guide/start-stop.adoc new file mode 100644 index 0000000..c136397 --- /dev/null +++ b/manual/src/main/asciidoc/user-guide/start-stop.adoc @@ -0,0 +1,439 @@ +// +// 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. +// + +=== Start, stop, restart, connect + +==== Start + +Apache Karaf supports different start mode: + +* the "regular" mode starts Apache Karaf in foreground, including the shell console. +* the "server" mode starts Apache Karaf in foreground, without the shell console. +* the "background" mode starts Apache Karaf in background. + +You can also manage Apache Karaf as a system service (see link:wrapper[System Service] section of this manual). + +===== Regular mode + +The regular mode uses the `bin/karaf` Unix script (`bin\karaf.bat` on Windows). It's the default start process. + +It starts Apache Karaf as a foreground process, and displays the shell console. + +On Unix: + +---- +bin/karaf + __ __ ____ + / //_/____ __________ _/ __/ + / ,< / __ `/ ___/ __ `/ /_ + / /| |/ /_/ / / / /_/ / __/ + /_/ |_|\__,_/_/ \__,_/_/ + + Apache Karaf (3.0.0) + +Hit '<tab>' for a list of available commands +and '[cmd] --help' for help on a specific command. +Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown Karaf. + +karaf@root()> +---- + +On Windows: + +---- +bin\karaf.bat + __ __ ____ + / //_/____ __________ _/ __/ + / ,< / __ `/ ___/ __ `/ /_ + / /| |/ /_/ / / / /_/ / __/ + /_/ |_|\__,_/_/ \__,_/_/ + + Apache Karaf (3.0.0) + +Hit '<tab>' for a list of available commands +and '[cmd] --help' for help on a specific command. +Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown Karaf. + +karaf@root()> +---- + +[NOTE] +==== +Closing the console or shell window will cause Apache Karaf to terminate. +==== + +===== Server mode + +The server mode starts Apache Karaf as a foreground process, but it doesn't start the shell console. + +To use this mode, you use the `server` argument to the `bin/karaf` Unix script (`bin\karaf.bat` on Windows). + +On Unix: + +---- +bin/karaf server + +---- + +On Windows: + +---- +bin\karaf.bat server + +---- + +[NOTE] +==== +Closing the console or shell window will cause Apache Karaf to terminate. +==== + +You can connect to the shell console using SSH or client (see the Connect section in this page). + +===== Background mode + +The background mode starts Apache Karaf as a background process. + +To start in background mode, you have to use `bin/start` Unix script (`bin\start.bat` on Windows). + +On Unix: + +---- +bin/start +---- + +On Windows: + +---- +bin\start.bat +---- + +You can connect to the shell console using SSH or client (see the Connect section in this page). + +===== Clean start + +Apache Karaf stores all previously applications installed and changes that you did in the data folder. + +If you want to start from a clean state, you can remove the data folder. + +For convenience, you can use the `clean` argument to the `bin/karaf` Unix script (`bin\karaf.bat` on Windows). + +On Unix: + +---- +bin/karaf clean +---- + +---- +bin/start clean +---- + +On Windows: + +---- +bin\karaf.bat clean +---- + +---- +bin\start.bat clean +---- + +===== Customize variables + +Apache Karaf accepts environment variables: + +* `JAVA_MIN_MEM`: minimum memory for the JVM (default is 128M). +* `JAVA_MAX_MEM`: maximum memory for the JVM (default is 512M). +* `JAVA_PERM_MEM`: minimum perm memory for the JVM (default is JVM default value). +* `JAVA_MAX_PERM_MEM`: maximum perm memory for the JVM (default is JVM default value). +* `KARAF_HOME`: the location of your Apache Karaf installation (default is found depending where you launch the startup script). +* `KARAF_BASE`: the location of your Apache Karaf base (default is `KARAF_HOME`). +* `KARAF_DATA`: the location of your Apache Karaf data folder (default is `KARAF_BASE/data`). +* `KARAF_ETC`: the location of your Apache Karaf etc folder (default is `KARAF_BASE/etc`). +* `KARAF_OPTS`: extra arguments passed to the Java command line (default is null). +* `KARAF_DEBUG`: if 'true', enable the debug mode (default is null). If debug mode is enabled, Karaf starts a JDWP socket on port 5005. You can plug your IDE to define breakpoints, and run step by step. + +You can define these environment variables in `bin/setenv` Unix script (`bin\setenv.bat` on Windows). + +For instance, to set the minimum and maximum memory size for the JVM, you can define the following values: + +On Unix: + +---- +# Content of bin/setenv +export JAVA_MIN_MEM=256M +exoprt JAVA_MAX_MEM=1024M +---- + +On Windows: + +---- +rem Content of bin\setenv.bat +set JAVA_MIN_MEM=256M +set JAVA_MAX_MEM=1024M +---- + +===== Connect + +Even if you start Apache Karaf without the console (using server or background modes), you can connect to the console. +This connection can be local or remote. It means that you can access to Karaf console remotely. + +To connect to the console, you can use the `bin/client` Unix script (`bin\client.bat` on Windows). + +On Unix: + +---- +bin/client +Logging in as karaf +360 [pool-2-thread-3] 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()> +---- + +On Windows: + +---- +bin\client.bat +Logging in as karaf +360 [pool-2-thread-3] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key: + __ __ ____ + / //_/____ __________ _/ __/ + / ,< / __ `/ ___/ __ `/ /_ + / /| |/ /_/ / / / /_/ / __/ + /_/ |_|\__,_/_/ \__,_/_/ + + Apache Karaf (3.0.0-SNAPSHOT) + +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()> +---- + +By default, `client` tries to connect on localhost, on port 8101 (the default Apache Karaf SSH port). + +`client` accepts different options to let you connect on a remote Apache Karaf instance. You can use `--help` to get details about the options: + +On Unix: + +---- +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 +---- + +On Windows: + +---- +bin\client.bat --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 +---- + +Actually, `client` is a SSH client. You can use any SSH client to connect, like OpenSSH (ssh command) on Unix, or Putty on Windows. + +For instance, on Unix, you can do: + +---- +ssh karaf@localhost -p 8101 +Authenticated with partial success. +Authenticated with partial success. +Authenticated with partial success. +Password authentication +Password: + __ __ ____ + / //_/____ __________ _/ __/ + / ,< / __ `/ ___/ __ `/ /_ + / /| |/ /_/ / / / /_/ / __/ + /_/ |_|\__,_/_/ \__,_/_/ + + Apache Karaf (3.0.0-SNAPSHOT) + +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()> +---- + +==== Stop + +When you start Apache Karaf in regular mode, the `logout` command or CTRL-D key binding logout from the console and shutdown Apache Karaf. + +When you start Apache Karaf in background mode (with the `bin/start` Unix script (`bin\start.bat` on Windows)), you can use the `bin/stop` Unix script (`bin\stop.bat` on Windows). + +More generally, you can use the `shutdown` command (on the Apache Karaf console) that work in any case. + +The `shutdown` command is very similar to the the `shutdown` Unix command. + +To shutdown Apache Karaf now, you can simple using `shutdown`: + +---- +karaf@root()> shutdown -h +Confirm: halt instance root (yes/no): +---- + +The `shutdown` command asks for a confirmation. If you want to bypass the confirmation step, you can use the `-f` (`--force`) option: + +---- +karaf@root()> shutdown -f +---- + +You can also use directly `halt` which is an alias to `shutdown -f -h`. + +The `shutdown` command accepts a time argument. With this argument, you can define when you want to shutdown the Apache Karaf container. + +The time argument can have different formats. First, it can be an absolute time in the format hh:mm, in which hh is the hour (1 or 2 digits) and mm is the minute of the hour +(in two digits). Second, it can be in the format m (or +m), in which m is the number of minutes to wait. The word `now` is an alias for 0. + +For instance, the following command will shutdown Apache Karaf at 10:35am: + +---- +karaf@root()> system:shutdown 10:35 +---- + +Another example to shutdown Apache Karaf in 10 minutes: + +---- +karaf@root()> system:shutdown 10 +---- + +Like for other commands, you can find details on the `shutdown` command man page: + +---- +karaf@root()> shutdown --help +DESCRIPTION + system:shutdown + + Shutdown Karaf. + +SYNTAX + system:shutdown [options] [time] + +ARGUMENTS + time + Shutdown after a specified delay. The time argument can have different formats. First, it can be an abolute time in the format hh:mm, in which hh is the hour (1 or 2 digits) and mm is the minute of the hour (in two digits). Second, it can be in the format +m, in which m is the number of minutes to + wait. The word now is an alias for +0. + +OPTIONS + -c, --clean, --clean-all, -ca + Force a clean restart by deleting the data directory + -f, --force + Force the shutdown without confirmation message. + -h, --halt + Halt the Karaf container. + --help + Display this help message + -cc, --clean-cache, -cc + Force a clean restart by deleting the cache directory + -r, --reboot + Reboot the Karaf container. +---- + +==== Status + +When you start Apache Karaf in background mode, you may want to check the current status. + +To do so, you can use the `bin/status` Unix script (`bin\status.bat` on Windows). + +[NOTE] +==== +The script returns 0 exit code if Apache Karaf is running, 1 exit code else. +==== + +On Unix: + +---- +bin/status +Not Running ... +---- + +---- +bin/status +Running ... +---- + +On Windows: + +---- +bin\status.bat +Not Running ... +---- + +---- +bin\status.bat +Running ... +---- + +==== Restart + +The `shutdown` command accepts the `-r` (`--restart`) option to restart Apache Karaf: + +---- +karaf@root()> system:shutdown -r +---- + +[NOTE] +==== +This command does not start a new JVM. It simply restarts the OSGi framework. +==== + +==== SystemMBean + +Apache Karaf provides the JMX SystemMBean dedicated to control of the container itself. + +The SystemMBean object name is `org.apache.karaf:type=system`. + +The SystemMBean provides different attributes and operations, especially operations to halt or reboot the container: + +* `reboot()` reboots Apache Karaf now (without cleaning the cache) +* `reboot(time)` reboots Apache Karaf at a given time (without cleaning the cache). The time format is the same as the time argument of the `shutdown` command. +* `rebootCleanCache(time)` reboots Apache Karaf at a given time, including the cleanup of the cache. +* `rebootCleanAll(time)` reboots Apache Karaf at a given time, including the cleanup of the whole data folder. +* `halt()` shutdown Apache Karaf now. +* `halt(time)` shutdown Apache Karaf at a given time. The time format is the same as the time argument of the `shutdown` command. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/tuning.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/tuning.adoc b/manual/src/main/asciidoc/user-guide/tuning.adoc new file mode 100644 index 0000000..756ba7f --- /dev/null +++ b/manual/src/main/asciidoc/user-guide/tuning.adoc @@ -0,0 +1,159 @@ +// +// 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. +// + +=== Tuning + +==== Garbage Collection + +Like any Java applications, Apache Karaf uses a JVM. An important feature of the JVM is the Garbage Collector. + +Apache Karaf default configuration is sized for small to medium needs and to work on most machine. + +That's why this default configuration may appear like "small". + +By default, Apache Karaf uses: + +* `-Xms128M` +* `-Xmx512M` +* `-XX:+UnlockDiagnosticVMOptions` +* `-XX:+UnsyncloadClass` + +On Sun/Oracle JVM: +* the Perm size is the JVM default + +On IBM JVM and AIX system: +* `-Xverify:none` +* `-Xdump:heap` +* `-Xlp` + +For any container, it's always difficult to predict the usage of the resources and the behaviour of the artifacts deployed. + +Generally speaking, a good approach for tuning is to enable `-verbose:gc` and use tools like VisualVM to identify the potentials +memory leaks, and see the possible optimisation of the spaces and GC. + +You can find introduction about GC here: http://www.oracle.com/webfolder/technetwork/tutorials/obe/java/gc01/index.html + +===== Java 6 + +If you have enough resources available on the machine, a good configuration may be: + +* `-server` +* `-Xmx1024M` +* `-XX:MaxPermSize=640M` +* `-XX:+UseConcMarkSweepGC` +* `-XX:+UseParNewGC` +* `-XX:+CMSClassUnloadingEnabled` + +It will give more resources to Apache Karaf, and avoid some perm space saturation if you do a lot of bundles refresh. + +See http://www.oracle.com/technetwork/java/javase/gc-tuning-6-140523.html for details about Java 6 tuning. + +===== Java 7 + +Java 7 introduces a new GC algorithm: the GC1. + +Depending of the use cases (and usage of the heap), the new GC1 algorithm can give good performance improvements: + +* `-XX:+UseG1GC` +* `-XX:-UseAdaptiveSizePolicy` + +See http://docs.oracle.com/javase/7/docs/technotes/guides/vm/G1.html for details about Java 7 GC1 tuning. + +You can find a good article about Java 7 tuning here: http://java-is-the-new-c.blogspot.de/2013/07/tuning-and-benchmarking-java-7s-garbage.html + +==== Threads + +In high loaded system, the number of threads can be very large. + +===== WebContainer + +If you use the Apache Karaf WebContainer, the Jetty connectors create threads to handle the incoming HTTP requests. + +The `etc/jetty.xml` configuration file allows you to tune the Jetty connector. + +For instance, the following connector configuration: + +---- + <Call name="addConnector"> + <Arg> + <New class="org.eclipse.jetty.server.nio.SelectChannelConnector"> + <Set name="host"> + <Property name="jetty.host" /> + </Set> + <Set name="port"> + <Property name="jetty.port" default="8181" /> + </Set> + <Set name="maxIdleTime">300000</Set> + <Set name="Acceptors">2</Set> + <Set name="statsOn">false</Set> + <Set name="confidentialPort">8443</Set> + <Set name="lowResourcesConnections">20000</Set> + <Set name="lowResourcesMaxIdleTime">5000</Set> + </New> + </Arg> + </Call> +---- + +defines the following properties: + +* `maxIdleTime` is the maximum inactivity time for a connection. +* `lowResourcesConnections` defines the number of connections. If the current number of connections is greater than + this value, the status is "low on resources". In that case, a new connection timeout is applied: the `lowResourceMaxIdleTime`. +* `Acceptors` defines the number of threads for incoming connections. + +===== Apache Camel + +For instance, if you use Apache Camel inside Apache Karaf, Camel components can create a lot of threads. + +Apache Camel use the notion of `threadPoolProfile` to control the threads creation. + +For instance, the following Camel configuration defines a pool creation strategy: + +---- +<threadPoolProfile id="defaultThreadPoolProfile" defaultProfile="true" + poolSize="10" maxPoolSize="20" maxQueueSize="1000" + rejectedPolicy="CallerRuns"/> +---- + +See the http://camel.apache.org[Apache Camel website] for details. + +===== Apache CXF + +Apache CXF uses workqueues to handle server request/response. + +You may see a `etc/org.apache.cxf.workqueues-default.cfg` configuration file. It's the default configuration applied +to all workqueues (a workqueue can be associated to a specific endpoint). + +On a workqueue, you can define the following properties about the threads: + +* `org.apache.cxf.workqueue.default.highWaterMark` defines the maximum number of threads. +* `org.apache.cxf.workqueue.default.lowWaterMark` defines the minimum number of threads. +* `org.apache.cxf.workqueue.default.initialSize` defines the initial number of threads. + +See the http://cxf.apache.org[Apache CXF website] for details. + +==== System packages + +The `etc/jre.properties` defines the packages directly provided by the JVM. + +Most of the time, the default configuration in Apache Karaf is fine and works in most of the use cases. + +However, some times, you may want to not use the packages provided by the JVM, but the same packages provided by a bundle. + +For instance, the JAXB version provided by the JVM is "old", and you want to use new JAXB bundles. + +In that case, you have to comment the packages in `etc/jre.properties` to avoid to be provided by the JVM and use the +ones from the bundles. + + http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/urls.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/urls.adoc b/manual/src/main/asciidoc/user-guide/urls.adoc new file mode 100644 index 0000000..7922ed7 --- /dev/null +++ b/manual/src/main/asciidoc/user-guide/urls.adoc @@ -0,0 +1,65 @@ +// +// 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. +// + +=== Artifacts repositories and URLs + +The main information provided by a feature is the set of OSGi bundles that defines the application. +Such bundles are URLs pointing to the actual bundle jars. For example, one would write the following definition: + +---- +<bundle>http://repo1.maven.org/maven2/org/apache/servicemix/nmr/org.apache.servicemix.nmr.api/1.0.0-m2/org.apache.servicemix.nmr.api-1.0.0-m2.jar</bundle> +---- + +Doing this will make sure the above bundle is installed while installing the feature. + +However, Karaf provides several URL handlers, in addition to the usual ones (file, http, etc...). +One of these is the Maven URL handler, which allow reusing maven repositories to point to the bundles. + +You can deploy bundles from file system without using Maven + +As we can use file: as protocol handler to deploy bundles, you can use the following syntax to deploy bundles when they are +located in a directory which is not available using Maven + +---- +<bundle>file:base/bundles/org.apache.servicemix.nmr.api-1.0.0-m2.jar</bundle> +---- + +[NOTE] +==== +The path is relative to the Apache Karaf installation directory +==== + +==== Maven URL Handler + +The equivalent of the above bundle would be: + +---- +<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.api/1.0.0-m2</bundle> +---- + +In addition to being less verbose, the Maven url handlers can also resolve snapshots and can use a local copy of the jar if one is available in your Maven local repository. + +The `org.ops4j.pax.url.mvn` bundle resolves `mvn` URLs. It can be configured using the file `etc/org.ops4j.pax.url.cfg` + +The most important property is : + +* `org.ops4j.pax.url.mvn.repositories` : Comma separated list of repository remote repository URLs that are checked in order of occurence when resolving maven artifacts + +By default, snapshots are disabled. To enable an URL for snapshots append @snapshots to a repository entry. For example + +---- +http://www.example.org/repo@snapshots +---- + +Repositories on the local machine are supported through `file:/` URLs. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/webconsole.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/webconsole.adoc b/manual/src/main/asciidoc/user-guide/webconsole.adoc new file mode 100644 index 0000000..dd61a5f --- /dev/null +++ b/manual/src/main/asciidoc/user-guide/webconsole.adoc @@ -0,0 +1,61 @@ +// +// 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. +// + +=== WebConsole + +Apache Karaf provides an optional WebConsole. + +This WebConsole provides a graphical web GUI to see and manage your Apache Karaf container. + +You can use the WebConsole to: + +* manage Apache Karaf features +* manage OSGi bundles +* manage the instances +* manage the confgurations +* manage the log service + +The WebConsole is extensible via a plugins system. Some applications can add new pages to the WebConsole. +For instance, Apache Karaf Cellar provides additional pages to administrate cluster groups, nodes, etc. + +==== Installation + +To enable the Apache Karaf WebConsole, you just have to install the `webconsole` feature: + +---- +karaf@root()> feature:install webconsole +---- + +The `webconsole` feature automatically installs the `http` feature (see the [WebContainer section|webcontainer] for details). + +==== Access + +The Apache Karaf WebConsole uses the WebContainer port number (see the [WebContainer section|webcontainer] for details) +with the `/system/console` context. + +By default, the Apache Karaf WebContainer port number is `8181`. + +It means that the Apache Karaf WebConsole is accessible on the following URL: http://localhost:8181/system/console + +As the Apache Karaf WebConsole uses the security framework, an username and password will be prompted. + +You have to enter an username/password from the `karaf` realm. By default, you can use `karaf`/`karaf`. + +See the link:security[Security section] for details. + +[NOTE] +==== +Only users with the `admin` role are allowed to logon on the Apache Karaf WebConsole. +Right now, the WebConsole doesn't use RBAC system as we have for console commands, or MBeans. +==== \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/webcontainer.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/webcontainer.adoc b/manual/src/main/asciidoc/user-guide/webcontainer.adoc new file mode 100644 index 0000000..59608c8 --- /dev/null +++ b/manual/src/main/asciidoc/user-guide/webcontainer.adoc @@ -0,0 +1,292 @@ +// +// 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. +// + +==== WebContainer (JSP/Servlet) + +Apache Karaf can act a complete WebContainer, fully supporting JSP/Servlet specification. + +Apache Karaf WebContainer supports both: + +* WAB (WebApplication Bundles) which are OSGi native web applications +* WAR (WebApplication aRchives) which are non-OSGi web applications (the same as you can deploy in any web container like Apache Tomcat) + +To enable the Apache Karaf WebContainer, you just have to install the `war` feature: + +---- +karaf@root()> feature:install war +---- + +[NOTE] +==== +The installation of the `webconsole` feature automatically installs the `war` feature. +==== + +The `war` feature provides: + +* an embedded web container (powered by Jetty), with its configuration +* a set of console commands +* a new war deployer + +===== Configuration + +The default port used by the WebContainer is 8181. + +The WebContainer configuration is in the `etc/jetty.xml` configuration file. + +The `etc/jetty.xml` is a standard Eclipse Jetty configuration file. + +The default Apache Karaf WebContainer `etc/jetty.xml` contains: + +---- +<?xml version="1.0"?> +<!-- + 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. +--> +<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting// +DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd";> + +<Configure class="org.eclipse.jetty.server.Server"> + + <!-- =========================================================== --> + <!-- Set connectors --> + <!-- =========================================================== --> + <!-- One of each type! --> + <!-- =========================================================== --> + + <!-- Use this connector for many frequently idle connections and for + threadless continuations. --> + <Call name="addConnector"> + <Arg> + <New class="org.eclipse.jetty.server.nio.SelectChannelConnector"> + <Set name="host"> + <Property name="jetty.host" /> + </Set> + <Set name="port"> + <Property name="jetty.port" default="8181" /> + </Set> + <Set name="maxIdleTime">300000</Set> + <Set name="Acceptors">2</Set> + <Set name="statsOn">false</Set> + <Set name="confidentialPort">8443</Set> + <Set name="lowResourcesConnections">20000</Set> + <Set name="lowResourcesMaxIdleTime">5000</Set> + </New> + </Arg> + </Call> + + <!-- =========================================================== --> + <!-- Configure Authentication Realms --> + <!-- Realms may be configured for the entire server here, or --> + <!-- they can be configured for a specific web app in a context --> + <!-- configuration (see $(jetty.home)/contexts/test.xml for an --> + <!-- example). --> + <!-- =========================================================== --> + <Call name="addBean"> + <Arg> + <New class="org.eclipse.jetty.plus.jaas.JAASLoginService"> + <Set name="name">karaf</Set> + <Set name="loginModuleName">karaf</Set> + <Set name="roleClassNames"> + <Array type="java.lang.String"> + <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal + </Item> + </Array> + </Set> + </New> + </Arg> + </Call> + <Call name="addBean"> + <Arg> + <New class="org.eclipse.jetty.plus.jaas.JAASLoginService"> + <Set name="name">default</Set> + <Set name="loginModuleName">karaf</Set> + <Set name="roleClassNames"> + <Array type="java.lang.String"> + <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal + </Item> + </Array> + </Set> + </New> + </Arg> + </Call> + +</Configure> +---- + +The `SelectChannelConnector` defines the default connector of the WebContainer. + +This connector defines the 8181 port number for the HTTP protocol (`port` property), and the 8443 port number for the +HTTPS protocol (`confidentialPort` property). + +By default, Apache Karaf bind these ports on all network interfaces (`0.0.0.0`). You can config the `host` property +to bind on a specific network interface (with a given IP address). + +The following resources give you details about advanced `etc/jetty.xml` configurations: + +* http://wiki.eclipse.org/Jetty/Howto/Configure_Jetty[Standard configuration] +* http://wiki.eclipse.org/Jetty/Howto/Configure_SSL[Enable SSL] +* http://wiki.eclipse.org/Jetty/Reference/jetty.xml_syntax[Reference] + +===== Deploy + +Apache Karaf WebContainer is able to deploy: + +* pure OSGi WebApplication Bundle (WAB) +* "classical" standard WebApplication aRchive (WAR) + +====== WAB (WebApplication Bundle) + +A WAB is a standard WAR or JAR archive containing at least the following properties in the MANIFEST: + +* `Bundle-ManifestVersion: 2` defines that the bundle follows the rules of R4 specification. +* `Bundle-SymbolicName` specifies a unique, non-localizable name for the bundle. This name should be based on the + reverse domain name convention. +* `Web-ContextPath` specifies the location of the web application. + +WAB can be deployed directly in Apache Karaf, for instance, by dropping the archive in the `deploy` folder, or using the +`bundle:install` command. + +For instance, the Apache Karaf manual (documentation) is available as a WAB that you can deploy directly in a running instance: + +---- +karaf@root()> bundle:install -s mvn:org.apache.karaf/manual/3.0.0/war +---- + +====== WAR (WebApplication aRchive) + +Apache Karaf allows you to deploy directly WAR files without repackaging as WAB. + +Using the `webbundle` prefix and providing headers directly on the URL, Apache Karaf creates a WAB "on the fly". + +For instance, you can deploy the Apache Tomcat sample non-OSGi "classical" WAR with the following command: + +---- +karaf@root()> bundle:install -s "webbundle:http://tomcat.apache.org/tomcat-7.0-doc/appdev/sample/sample.war?Bundle-SymbolicName=tomcat-sample&Web-ContextPath=/sample"; +---- + +You can note the `webbundle` prefix, and the `Bundle-SymbolicName` and `Web-ContextPath` headers on the URL. + +===== Commands + +====== `http:list` + +The `http:list` lists the available Servlets deployed in the WebContainer. + +For instance, if you have installed the Apache Karaf WebConsole, you can see the WebConsole Servlets: + +---- +karaf@root()> http:list +ID | Servlet | Servlet-Name | State | Alias | Url +----------------------------------------------------------------------------------------------------- +113 | ResourceServlet | /res | Deployed | /system/console/res | [/system/console/res/*] +113 | KarafOsgiManager | ServletModel-2 | Undeployed | /system/console | [/system/console/*] +113 | KarafOsgiManager | ServletModel-5 | Deployed | /system/console | [/system/console/*] +---- + +The `ID` is the ID of the bundle which provides the servlet (`113` here). + +The `State` is the current state of the Servlet (`Deployed` or `Undeployed`). + +The `Url` is the URL where the Servlet is available. + +====== `web:list` + +The `web:list` command lists the WebApplication Bundles ("native" WAB or "wrapped WAR") deployed in the WebContainer. + +For instance, if you installed the Apache Karaf manual WAR file as described previously, you can see it with `web:list`: + +---- +karaf@root()> web:list +ID | State | Web-State | Level | Web-ContextPath | Name +--------------------------------------------------------------------------------------------------- +111 | Active | Deployed | 80 | /karaf-doc | Apache Karaf :: Manual (3.0.0) +---- + +====== `web:stop` + +The `web:stop` command stops a web application in the WebContainer. The `web:stop` command expects a `id` argument +corresponding to the bundle ID (as displayed by the `web:list` command). + +For instance, to stop the Apache Karaf manual web application: + +---- +karaf@root()> web:stop 111 +---- + +====== `web:start` + +The `web:start` command starts a web application in the WebContainer. The `web:start` command expects a `id` argument +corresponding to the bundle ID (as displayed by the `web:list` command). + +For instance, to start the Apache Karaf manual web application: + +---- +karaf@root()> web:start 111 +---- + +===== JMX HttpMBean + +On the JMX layer, you have a MBean dedicated to the manipulation of the Servlets: the HttpMBean. + +The ObjectName to use is `org.apache.karaf:type=http,name=*`. + +====== Attributes + +The `Servlets` attribute provides a tabular data providing the list of deployed Servlets including: + +* `Alias` is the Servlet URL alias. +* `Bundle-ID` is the ID of the bundle which provides this Servlet. +* `Servlet` is the class name of the Servlet. +* `State` is the current Servlet state (`Deployed` or `Undeployed`). +* `URL` is the URL of the Servlet (the Servlet context path). + +===== JMX WebMBean + +On the JMX layer, you have a MBean dedicated to the manipulation of the Web Applications: the WebMBean. + +The ObjectName to use is `org.apache.karaf:type=web,name=*`. + +====== Attributes + +The `WebBundles` attribute provides a tabular data providing the list of deployed Web Applications including: + +* `ID` is the ID of the bundle providing the Web Application. +* `Level` is the bundle start level. +* `Name` is the bundle symbolic name providing the Web Application. +* `State` is the current state of the bundle. +* `Web-ContextPath` is the context path of the Web Application. +* `Web-State` is the current status of the Web Application (`Deployed` or `Undeployed`). + +====== Operations + +* `start(id)` starts the web context of the bundle with `id`. +* `start(list)` starts the web context of the bundles with ID in the provided `list`. +* `stop(id)` stops the web context of the bundle with `id`. +* `stop(list)` stops the web context of the bundles with ID in the provided `list`. + http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/user-guide/wrapper.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/wrapper.adoc b/manual/src/main/asciidoc/user-guide/wrapper.adoc new file mode 100644 index 0000000..0a65e28 --- /dev/null +++ b/manual/src/main/asciidoc/user-guide/wrapper.adoc @@ -0,0 +1,407 @@ +// +// 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. +// + +=== Integration in the operating system: the Service Wrapper + +In the previous chapter, we saw the different scripts and commands to start, stop, restart Apache Karaf. + +Instead of using these commands and scripts, you can integrate Apache Karaf directly in your operating system service control. + +Apache Karaf provides the "Service Wrapper". The service wrapper allows you to directly integrate Apache Karaf: + +* like a native Windows Service +* like a Unix daemon process + +The "Service Wrapper" correctly handles "user's log outs" under Windows, service dependencies, and the ability to run services which interact with the desktop. + +It also includes advanced fault detection software which monitors an application. +The "Service Wrapper" is able to detect crashes, freezes, out of memory and other exception events, then automatically react by restarting Apache Karaf with a minimum of delay. +It guarantees the maximum possible uptime of Apache Karaf. + +==== Supported platforms + +* Windows 8, 7, 2008 R2, 2003, Vista (32 and 64 bits architecture) +* Linux RedHat Enterprise Linux, Debian, CentOS, Fedora, Ubuntu (32 and 64 bits architecture) +* FreeBSD 9.x, 8.x +* AIX 5.x, 6.x, 7.x (Power architecture) +* Solaris 8, 9, 10 (x86/Sparc, 32 and 64 bits architecture) +* HP-UX 10.x, 11.x (32 and 64 bits architecture) +* SGI Irix +* MacOS X + +==== Installation + +Apache Karaf Service Wrapper is an optional feature. You have to install the "Service Wrapper" installer first. + +In the console: + +---- +karaf@root()> feature:install service-wrapper +---- + +Now, you have the `wrapper:install` command, to "register" Apache Karaf as service/daemon on your system: + +---- +karaf@root()> wrapper:install --help +DESCRIPTION + wrapper:install + + Install the container as a system service in the OS. + +SYNTAX + wrapper:install [options] + +OPTIONS + -d, --display + The display name of the service. + (defaults to karaf) + --help + Display this help message + -s, --start-type + Mode in which the service is installed. AUTO_START or DEMAND_START (Default: AUTO_START) + (defaults to AUTO_START) + -n, --name + The service name that will be used when installing the service. (Default: karaf) + (defaults to karaf) + -D, --description + The description of the service. + (defaults to ) +---- + +==== Installation + +Karaf Wrapper is an optional feature. To install it, simply type: + +---- +karaf@root> feature:install wrapper +---- + +Once installed, wrapper feature will provide `wrapper:install` new command in the Karaf shell: + +---- +karaf@root> wrapper:install --help +DESCRIPTION + wrapper:install + + Install the container as a system service in the OS. + +SYNTAX + wrapper:install [options] + +OPTIONS + -s, --start-type + Mode in which the service is installed. AUTO_START or DEMAND_START (Default: AUTO_START) + (defaults to AUTO_START) + --help + Display this help message + -n, --name + The service name that will be used when installing the service. (Default: karaf) + (defaults to karaf) + -d, --display + The display name of the service. + -D, --description + The description of the service. + (defaults to ) +---- + +The `wrapper:install` command detects the running Operating Service and provide the service/daemon ready to be integrated in your system. + +For instance, on a Ubuntu/Debian Linux system: + +---- +karaf@root()> wrapper:install +Creating file: /opt/apache-karaf-3.0.5/bin/karaf-wrapper +Creating file: /opt/apache-karaf-3.0.5/bin/karaf-service +Creating file: /opt/apache-karaf-3.0.5/etc/karaf-wrapper.conf +Creating file: /opt/apache-karaf-3.0.5/lib/libwrapper.so +Creating file: /opt/apache-karaf-3.0.5/lib/karaf-wrapper.jar +Creating file: /opt/apache-karaf-3.0.5/lib/karaf-wrapper-main.jar + +Setup complete. You may wish to tweak the JVM properties in the wrapper configuration file: + /opt/apache-karaf-3.0.5/etc/karaf-wrapper.conf +before installing and starting the service. + + +Ubuntu/Debian Linux system detected: + To install the service: + $ ln -s /opt/apache-karaf-3.0.5/bin/karaf-service /etc/init.d/ + + To start the service when the machine is rebooted: + $ update-rc.d karaf-service defaults + + To disable starting the service when the machine is rebooted: + $ update-rc.d -f karaf-service remove + + To start the service: + $ /etc/init.d/karaf-service start + + To stop the service: + $ /etc/init.d/karaf-service stop + + To uninstall the service : + $ rm /etc/init.d/karaf-service + +---- + +You can note that `wrapper:install` command detected the running operating system ("Ubuntu/Debian Linux system detected"). + +You have a complete explanation and list of system commands to perform to integrate Apache Karaf in your systemV: + +---- +ln -s /opt/apache-karaf-3.0.5/bin/karaf-service /etc/init.d/ +update-rc.d karaf-service defaults +---- + +Karaf also supports systemd service, so you can use systemctl instead of SystemV based service: + +---- +systemctl enable /opt/apache-karaf-3.0.5/bin/karaf.service +---- + +This will enable Karaf at system boot. + +==== Uninstall + +The `wrapper:install` provides the system commands to perform to uninstall the service/daemon). + +For instance, on Ubuntu/Debian, to uninstall the Apache Karaf service, you have to remove the `karaf-service` script from the runlevel scripts: + +---- +rm /etc/init.d/karaf-service +---- + +If you prefered the systemd service instead of systemV: + +---- +systemctl disable karaf +---- + +You can remove the "Wrapper Service" installer after that: + +---- +karaf@root()> feature:uninstall service-wrapper +---- + +==== Note for MacOS users + +On MacOS you can install the service for an user or for the system. + +If you want to add bin/org.apache.karaf.KARAF as user service move this file into ~/Library/LaunchAgents/: + +---- +mv bin/org.apache.karaf.KARAF.plist ~/Library/LaunchAgents/ +---- + +If you want to add org.apache.karaf.KARAF as system service move this into /Library/LaunchDaemons: + +---- +sudo mv bin/org.apache.karaf.KARAF.plist /Library/LaunchDaemons/ +---- + +Change owner and rights: + +---- +sudo chown root:wheel /Library/LaunchDaemons/org.apache.karaf.KARAF.plist +sudo chmod u=rw,g=r,o=r /Library/LaunchDaemons/org.apache.karaf.KARAF.plist +---- + +You can test your service: + +---- +launchctl load ~/Library/LaunchAgents/org.apache.karaf.KARAF.plist +launchctl start org.apache.karaf.KARAF +launchctl stop org.apache.karaf.KARAF +---- + +Finally, after restart your session or system you can use launchctl command to start and stop your service. + +If you want to remove the service call: + +---- +launchctl remove org.apache.karaf.KARAF +---- + +==== Configuration + +When using scripts in the Apache Karaf `bin` folder, you can using `bin/setenv` Unix script (`bin\setenv.bat` on Windows) as described in the [Start, stop, restart, connect|start-stop] section of the documentation. + +[NOTE] +==== +The `bin/setenv` Unix script (`bin\setenv.bat` on Windows) is not used by the Apache Karaf Service Wrapper. +==== + +To configure Apache Karaf started by the Service Wrapper, you have to tune the `etc/karaf-wrapper.conf` file. If you provided the `name` option to the `wrapper:install` command, the file is `etc/karaf-yourname.conf`. + +In this file, you can configure the different environment variables used by Apache Karaf. The Service Wrapper installer automatically populate these variables for you during the installation (using `wrapper:install` command). +For instance: + +* `set.default.JAVA_HOME` is the `JAVA_HOME` used to start Apache Karaf (populated during Service Wrapper installation). +* `set.default.KARAF_HOME` is the location of your Apache Karaf installation (populated during Service Wrapper installation). +* `set.default.KARAF_BASE` is the location of your Apache Karaf installation (populated during Service Wrapper installation). +* `set.default.KARAF_DATA` is the location of the Apache Karaf data folder (populated during Service Wrapper installation). +* `set.default.KARAF_ETC` is the location of the Apache Karaf etc folder (populated during Service Wrapper installation). +* `wrapper.java.additional` is used to pass additional arguments to the Java command, indexed by the argument number. The next index to use is 11. +* `wrapper.java.initmemory` is the initial JVM memory size (the `-Xms`). It's not set by default (JVM default). +* `wrapper.java.maxmemory` is the maximum JVM memory size (the `-Xmx`). It's set to 512M by default. +* `wrapper.logfile` is the location of the Service Wrapper log file. It's set to `%KARAF_DATA%/log/wrapper.log` by default. +* `wrapper.logfile.loglevel` is the Service Wrapper log level. It's set to `INFO` by default. +* `wrapper.logfile.maxsize` is the Service Wrapper log file maximum size (before rotation). It's set to `10m` (10MB) by default. +* `wrapper.logfile.maxfiles` is the number of Service Wrapper log files created (and rotated). It's set to `5` by default. +* `wrapper.syslog.loglevel` is the integration with Unix syslog daemon. By default, it's set to `none` meaning disabled. +* `wrapper.ntservice.name` is Windows service specific and defines the Windows service name. It's set to the `name` option of the `wrapper:install` command, or `karaf` by default. +* `wrapper.ntservice.displayname` is Windows service specific and defines the Windows service display name. It's set to the `display` option of the `wrapper:install` command, or `karaf` by default. +* `wrapper.ntservice.description` is Windows service specific and defines the Windows service description. It's set to the `description` option of the `wrapper:install` command, or empty by default. +* `wrapper.ntservice.starttype` is Windows service specific and defines if the Windows service is started automatically with the service, or just on demand. It's set to `AUTO_START` by default, and could be switch to `DEMAND_START`. + +This is a example of generated `etc/karaf-wrapper.conf` 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. +# ------------------------------------------------------------------------ + +#******************************************************************** +# Wrapper Properties +#******************************************************************** +set.default.JAVA_HOME=/opt/jdk/1.7.0_21 +set.default.KARAF_HOME=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.5-SNAPSHOT +set.default.KARAF_BASE=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.5-SNAPSHOT +set.default.KARAF_DATA=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.5-SNAPSHOT/data +set.default.KARAF_ETC=/home/jbonofre/workspace/karaf/karaf/assemblies/apache-karaf/target/apache-karaf-3.0.5-SNAPSHOT/etc + +# Java Application +wrapper.working.dir=%KARAF_BASE% +wrapper.java.command=%JAVA_HOME%/bin/java +wrapper.java.mainclass=org.apache.karaf.wrapper.internal.Main +wrapper.java.classpath.1=%KARAF_HOME%/lib/karaf-wrapper.jar +wrapper.java.classpath.2=%KARAF_HOME%/lib/karaf.jar +wrapper.java.classpath.3=%KARAF_HOME%/lib/karaf-jaas-boot.jar +wrapper.java.classpath.4=%KARAF_HOME%/lib/karaf-wrapper-main.jar +wrapper.java.classpath.5=%KARAF_HOME%/lib/karaf-org.osgi.core.jar +wrapper.java.library.path.1=%KARAF_HOME%/lib/ + +# Application Parameters. Add parameters as needed starting from 1 +#wrapper.app.parameter.1= + +# JVM Parameters +# note that n is the parameter number starting from 1. +wrapper.java.additional.1=-Dkaraf.home=%KARAF_HOME% +wrapper.java.additional.2=-Dkaraf.base=%KARAF_BASE% +wrapper.java.additional.3=-Dkaraf.data=%KARAF_DATA% +wrapper.java.additional.4=-Dkaraf.etc=%KARAF_ETC% +wrapper.java.additional.5=-Dcom.sun.management.jmxremote +wrapper.java.additional.6=-Dkaraf.startLocalConsole=false +wrapper.java.additional.7=-Dkaraf.startRemoteShell=true +wrapper.java.additional.8=-Djava.endorsed.dirs=%JAVA_HOME%/jre/lib/endorsed:%JAVA_HOME%/lib/endorsed:%KARAF_HOME%/lib/endorsed +wrapper.java.additional.9=-Djava.ext.dirs=%JAVA_HOME%/jre/lib/ext:%JAVA_HOME%/lib/ext:%KARAF_HOME%/lib/ext + +# Uncomment to enable jmx +#wrapper.java.additional.n=-Dcom.sun.management.jmxremote.port=1616 +#wrapper.java.additional.n=-Dcom.sun.management.jmxremote.authenticate=false +#wrapper.java.additional.n=-Dcom.sun.management.jmxremote.ssl=false + +# Uncomment to enable YourKit profiling +#wrapper.java.additional.n=-Xrunyjpagent + +# Uncomment to enable remote debugging +#wrapper.java.additional.n=-Xdebug -Xnoagent -Djava.compiler=NONE +#wrapper.java.additional.n=-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005 + +# Initial Java Heap Size (in MB) +#wrapper.java.initmemory=3 + +# Maximum Java Heap Size (in MB) +wrapper.java.maxmemory=512 + + +#******************************************************************** +# Wrapper Logging Properties +#******************************************************************** +# Format of output for the console. (See docs for formats) +wrapper.console.format=PM + +# Log Level for console output. (See docs for log levels) +wrapper.console.loglevel=INFO + +# Log file to use for wrapper output logging. +wrapper.logfile=%KARAF_DATA%/log/wrapper.log + +# Format of output for the log file. (See docs for formats) +wrapper.logfile.format=LPTM + +# Log Level for log file output. (See docs for log levels) +wrapper.logfile.loglevel=INFO + +# Maximum size that the log file will be allowed to grow to before +# the log is rolled. Size is specified in bytes. The default value +# of 0, disables log rolling. May abbreviate with the 'k' (kb) or +# 'm' (mb) suffix. For example: 10m = 10 megabytes. +wrapper.logfile.maxsize=10m + +# Maximum number of rolled log files which will be allowed before old +# files are deleted. The default value of 0 implies no limit. +wrapper.logfile.maxfiles=5 + +# Log Level for sys/event log output. (See docs for log levels) +wrapper.syslog.loglevel=NONE + +#******************************************************************** +# Wrapper Windows Properties +#******************************************************************** +# Title to use when running as a console +wrapper.console.title=karaf + +#******************************************************************** +# Wrapper Windows NT/2000/XP Service Properties +#******************************************************************** +# WARNING - Do not modify any of these properties when an application +# using this configuration file has been installed as a service. +# Please uninstall the service before modifying this section. The +# service can then be reinstalled. + +# Name of the service +wrapper.ntservice.name=karaf + +# Display name of the service +wrapper.ntservice.displayname=karaf + +# Description of the service +wrapper.ntservice.description= + +# Service dependencies. Add dependencies as needed starting from 1 +wrapper.ntservice.dependency.1= + +# Mode in which the service is installed. AUTO_START or DEMAND_START +wrapper.ntservice.starttype=AUTO_START + +# Allow the service to interact with the desktop. +wrapper.ntservice.interactive=false +---- + +===== systemd + +The Karaf service wrapper also support Linux systemd service. http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/webapp/.livereload ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/.livereload b/manual/src/main/webapp/.livereload deleted file mode 100644 index b185045..0000000 --- a/manual/src/main/webapp/.livereload +++ /dev/null @@ -1,19 +0,0 @@ -# Lines starting with pound sign (#) are ignored. - -# additional extensions to monitor -#config.exts << 'haml' - -# exclude files with NAMES matching this mask -#config.exclusions << '~*' -# exclude files with PATHS matching this mask (if the mask contains a slash) -#config.exclusions << '/excluded_dir/*' -# exclude files with PATHS matching this REGEXP -#config.exclusions << /somedir.*(ab){2,4}.(css|js)$/ - -# reload the whole page when .js changes -#config.apply_js_live = false -# reload the whole page when .css changes -#config.apply_css_live = false - -# wait 100ms for more changes before reloading a page -#config.grace_period = 0.1 http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/webapp/WEB-INF/scalate/layouts/default.scaml ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/WEB-INF/scalate/layouts/default.scaml b/manual/src/main/webapp/WEB-INF/scalate/layouts/default.scaml deleted file mode 100644 index c88ba58..0000000 --- a/manual/src/main/webapp/WEB-INF/scalate/layouts/default.scaml +++ /dev/null @@ -1,116 +0,0 @@ --# --# Copyright (C) 2009-2010 the original author or authors. --# See the notice.md file distributed with this work for additional --# information regarding copyright ownership. --# --# 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. --# - --@ var body: String --@ var title : String = "Apache Karaf ${karaf.version} Guides" -- response.setContentType("text/html") - --# Only include the console if it's available and the engine is in dev mode. -- val include_console = engine.isDevelopmentMode && engine.resourceLoader.exists("/org/fusesource/scalate/console/console_head.scaml") - -!!! Basic -%html(lang="en") - %head - %meta(http-equiv="Content-Type" content="text/html; charset=utf-8") - %meta(name="description" content="description goes here") - %meta(name="keywords" content="keywords,goes,here") - %meta(name="author" content="The Apache Karaf Team") - - - if (include_console) - = include("/org/fusesource/scalate/console/console_head.scaml") - - %link(href={uri("/css/style.css")} rel="stylesheet" type="text/css") - %link(href={uri("/css/pygmentize.css")} rel="stylesheet" type="text/css") - - - if (include_console) - %link(href={uri("/css/scalate/console.css")} rel="stylesheet" type="text/css") - - %title - = title - - %body - %table{:width => "100%", :cellpadding => "0", :cellspacing => "0"} - %tr{:width => "100%"} - %td#cell-0-0{:colspan => "2"} - - %td#cell-0-1 - - %td#cell-0-2{:colspan => "2"} - - %tr{:width => "100%"} - %td#cell-1-0 - - %td#cell-1-1 - - %td#cell-1-2 - %div{:style => "padding: 5px;"} - #banner - = include("/_banner.ssp") - #top-menu - %table{:border => "0", :cellpadding => "1", :cellspacing => "0", :width => "100%"} - %tr - %td - %div{:align => "left"} - %td - %div{:align => "right"} - = include("/_quicklinks.ssp") - %td#cell-1-3 - - %td#cell-1-4 - - %tr{:width => "100%"} - %td#cell-2-0{:colspan => "2"} - - %td#cell-2-1 - %table - %tr{:height => "100%", :valign => "top"} - %td{:height => "100%"} - #wrapper-menu-page-right - #wrapper-menu-page-top - #wrapper-menu-page-bottom - #menu-page - = include("/_navigation.conf") - %td{:height =>"100%", :width => "100%"} - .wiki-content - !~~ body - %td#cell-2-2{:colspan => "2"} - - %tr{:width => "100%"} - %td#cell-3-0 - - %td#cell-3-1 - - %td#cell-3-2 - #footer - #site-footer - © 2008-2011 The Apache Software Foundation - %br - Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation. - %td#cell-3-3 - - %td#cell-3-4 - - %tr{:width => "100%"} - %td#cell-4-0{:colspan => "2"} - - %td#cell-4-1 - - %td#cell-4-2{:colspan => "2"} - - - if (include_console) - = include("/org/fusesource/scalate/console/console.scaml")
