Updated Branches: refs/heads/master 64de46f7b -> 625e1d2d6
[KARAF-2301] Add documentation about aliases and scripting Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/625e1d2d Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/625e1d2d Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/625e1d2d Branch: refs/heads/master Commit: 625e1d2d661e17abd7fc78cd99fc609a9435db5c Parents: 64de46f Author: Jean-Baptiste Onofré <[email protected]> Authored: Mon Dec 23 08:56:43 2013 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Mon Dec 23 08:56:43 2013 +0100 ---------------------------------------------------------------------- manual/src/main/webapp/users-guide/console.conf | 172 +++++++++++++++++++ 1 file changed, 172 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/625e1d2d/manual/src/main/webapp/users-guide/console.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/console.conf b/manual/src/main/webapp/users-guide/console.conf index 9af4062..4f0234c 100644 --- a/manual/src/main/webapp/users-guide/console.conf +++ b/manual/src/main/webapp/users-guide/console.conf @@ -235,6 +235,78 @@ When you type the tab key, Karaf tries to complete: * the command arguments * the command option +h3. Alias + +An alias is another name associated to a given command. + +The {{shell:alias}} command creates a new alias. For instance, to create the {{list-installed-features}} alias to the actual +{{feature:list -i}} command, you can do: + +{code} +karaf@root()> alias "list-features-installed = { feature:list -i }" +karaf@root()> list-features-installed +Name | Version | Installed | Repository | Description +--------------------------------------------------------------------------------------------------------- +standard | 3.0.0 | x | standard-3.0.0 | Karaf standard feature +config | 3.0.0 | x | standard-3.0.0 | Provide OSGi ConfigAdmin support +region | 3.0.0 | x | standard-3.0.0 | Provide Region Support +package | 3.0.0 | x | standard-3.0.0 | Package commands and mbeans +kar | 3.0.0 | x | standard-3.0.0 | Provide KAR (KARaf archive) support +ssh | 3.0.0 | x | standard-3.0.0 | Provide a SSHd server on Karaf +management | 3.0.0 | x | standard-3.0.0 | Provide a JMX MBeanServer and a set of MBeans in K +{code} + +At login, the Apache Karaf console reads the {{etc/shell.init.script}} file where you can create your aliases. +It's similar to a bashrc or profile file on Unix. + +{code} +// +// 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 script is run each time a shell is created. +// You can define here closures or variables that will be available +// in each session. +// +ld = { log:display $args } ; +lde = { log:exception-display $args } ; +la = { bundle:list -t 0 $args } ; +ls = { service:list $args } ; +cl = { config:list "(service.pid=$args)" } ; +halt = { system:shutdown -h -f $args } ; +help = { *:help $args | more } ; +man = { help $args } ; +log:list = { log:get ALL } ; +{code} + +You can see here the aliases available by default: + +* {{ld}} is a short form to display log (alias to {{log:display}} command) +* {{lde}} is a short form to display exceptions (alias to {{log:exception-display}} command) +* {{la}} is a short form to list all bundles (alias to {{bundle:list -t 0}} command) +* {{ls}} is a short form to list all services (alias to {{service:list}} command) +* {{cl}} is a short form to list all configurations (alias to {{config:list}} command) +* {{halt}} is a short form to shutdown Apache Karaf (alias to {{system:shutdown -h -f}} command) +* {{help}} is a short form to display help (alias to {{*:help}} command) +* {{man}} is the same as help (alias to {{help}} command) +* {{log:list}} displays all loggers and level (alias to {{log:get ALL}} command) + +You can create your own aliases in the {{etc/shell.init.script}} file. + h3. Key binding Like on most Unix environment, Karaf console support some key bindings: @@ -316,6 +388,106 @@ OPTIONS Again, you can find details and all options of these commands using {{help}} command or {{--help}} option. +h3. Scripting + +The Apache Karaf Console supports a complete scripting language, similar to bash or csh on Unix. + +The {{each}} ({{shell:each}}) command can iterate in a list: + +{code} +karaf@root()> list = [1 2 3]; each ($list) { echo $it } +1 +2 +3 +{code} + +You can create the list yourself (as in the previous example), or some commands can return a list too. + +We can note that the console created a "session" variable with the name {{list}} that you can access with {{$list}}. + +The {{$it}} variable is an implicit one corresponding to the current object (here the current iterated value from the +list). + +When you create a list with {{[]}}, Apache Karaf console creates a Java ArrayList. It means that you can use methods +available in the ArrayList objects (like get or size for instance): + +{code} +karaf@root()> list = ["Hello" world]; echo ($list get 0) ($list get 1) +Hello world +{code} + +We can note here that calling a method on an object is directly using {{(object method argument)}}. +Here {{($list get 0)}} means {{$list.get(0)}} where {{$list}} is the ArrayList. + +The {{class}} notation will display details about the object: + +{code} +karaf@root()> $list class +... +ProtectionDomain ProtectionDomain null + null + <no principals> + java.security.Permissions@6521c24e ( + ("java.security.AllPermission" "<all permissions>" "<all actions>") +) + + +Signers null +SimpleName ArrayList +TypeParameters [E] +{code} + +You can "cast" a variable to a given type. + +{code} +karaf@root()> ("hello world" toCharArray) +[h, e, l, l, o, , w, o, r, l, d] +{code} + +If it fails, you will see the casting exception: + +{code} +karaf@root()> ("hello world" toCharArray)[0] +Error executing command: [C cannot be cast to [Ljava.lang.Object; +{code} + +You can "call" a script using the {{shell:source}} command: + +{code} +karaf@root> shell:source script.txt +True! +{code} + +where {{script.txt}} contains: + +{code} +foo = "foo" +if { $foo equals "foo" } { + echo "True!" +} +{code} + +{warning} +The spaces are important when writing script. +For instance, the following script is not correct: + +{code} +if{ $foo equals "foo" } ... +{code} + +and will fail with: + +{code} +karaf@root> shell:source script.txt +Error executing command: Cannot coerce echo "true!"() to any of [] +{code} + +because a space is missing after the {{if}} statement. +{warning} + +As for the aliases, you can create init scripts in the {{etc/shell.init.script}} file. +You can also named you script with an alias. Actually, the aliases are just scripts. + h2. Security The Apache Karaf console supports a Role Based Access Control (RBAC) security mechanism. It means that depending of
