UNOMI-208 Improve documentation - Add documentation for SSH Shell commands.
Signed-off-by: Serge Huber <shu...@apache.org> Project: http://git-wip-us.apache.org/repos/asf/incubator-unomi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-unomi/commit/67657bdb Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/67657bdb Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/67657bdb Branch: refs/heads/UNOMI-180-CXS-GRAPHQLAPI Commit: 67657bdb11d3381f1cea81565ee41bf8f5a248f8 Parents: f502839 Author: Serge Huber <shu...@apache.org> Authored: Mon Nov 5 18:23:09 2018 +0100 Committer: Serge Huber <shu...@apache.org> Committed: Mon Nov 5 18:23:09 2018 +0100 ---------------------------------------------------------------------- manual/src/main/asciidoc/index.adoc | 2 + manual/src/main/asciidoc/shell-commands.adoc | 138 ++++++++++++++++++++++ 2 files changed, 140 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/67657bdb/manual/src/main/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/index.adoc b/manual/src/main/asciidoc/index.adoc index bf29433..ea1d4a1 100644 --- a/manual/src/main/asciidoc/index.adoc +++ b/manual/src/main/asciidoc/index.adoc @@ -68,6 +68,8 @@ include::consent-api.adoc[] include::building-and-deploying.adoc[] +include::shell-commands.adoc[] + include::extending-plugins.adoc[] include::custom-extensions.adoc[] http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/67657bdb/manual/src/main/asciidoc/shell-commands.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/shell-commands.adoc b/manual/src/main/asciidoc/shell-commands.adoc new file mode 100644 index 0000000..e69e2bc --- /dev/null +++ b/manual/src/main/asciidoc/shell-commands.adoc @@ -0,0 +1,138 @@ +// +// 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. +// +=== SSH Shell Commands + +Apache Unomi provides its own Apache Karaf Shell commands to make it easy to control the application +lifecycle or perform queries or modifications on the internal state of the system. + +All Apache Unomi-specific commands are namespaced and use the `unomi:` namespace. You can use the Apache Karaf Shell's +autocompletion to list all the commands available. + +==== Using the shell + +You can connect to the Apache Karaf SSH Shell using the following command: + + ssh -p 8102 karaf@localhost + +The default username/password is karaf/karaf. You should change this as soon as possible by editing the `etc/users.properties` file. + +Once connected you can simply type in : + + unomi: + +And hit the <tab> key to see the list of all the available Apache Unomi commands. Note that some commands +are only available when the application is started. + +You can also use the `help` command on any command such as in the following example: + +``` +karaf@root()> help unomi:migrate +DESCRIPTION + unomi:migrate + + This will Migrate your date in ES to be compliant with current version + +SYNTAX + unomi:migrate [fromVersionWithoutSuffix] + +ARGUMENTS + fromVersionWithoutSuffix + Origin version without suffix/qualifier (e.g: 1.2.0) + (defaults to 1.2.0) +``` +==== Lifecycle commands + +The commands control the lifecycle of the Apache Unomi server and are used to migrate, start or stop the server. + +.Table Lifecycle commands +|=== +|Command|Arguments|Description + +|migrate +|fromVersion +|This command must be used only when the Apache Unomi application is NOT STARTED. It will perform migration of the data stored in ElasticSearch using the argument fromVersion as a starting point. + +|stop +|n/a +|Shutsdown the Apache Unomi application + +|start +|n/a +|Starts the Apache Unomi application. Note that this state will be remembered between Apache Karaf launches, so in general it is only needed after a first installation or after a `migrate` command + +|version +|n/a +|Prints out the currently deployed version of the Apache Unomi application inside the Apache Karaf runtime. +|=== + +==== Runtime commands + +These commands are available once the application is running. If an argument is between brackets [] it means it is optional. + +.Table Runtime commands +|=== +|Command|Arguments|Description +|rule-list +|[--csv] +|Lists all the rules registered in the Apache Unomi server. If you add the "--csv" option the list will be output +as a CSV formatted table +|rule-view +|rule-id +|Dumps a single rule in JSON. The rule-id argument can be retrieved from the `rule-list` command output. +|rule-reset-stats +|n/a +|Resets the rule statistics. This is notably useful when trying to understand rule performance and impact +|event-tail +|n/a +|Dumps any incoming events to the Apache Unomi server to the console. Use CTRL+C to exit tail +|event-view +|event-id +|Dumps a single event in JSON. The `event-id` can be retrieved from the event-tail command output. +|action-list +|[--csv] +|Lists all the rule actions registered in the Apache Unomi server. This command is useful when developing plugins to +check that everything is properly registered. If you add the "--csv" option the list will be output + as a CSV formatted table +|action-view +|action-id +|Dumps a single action in JSON. The action-id argument can be retrieved from the `action-list` command output. +|profile-list +|[--csv] +|List the last 10 modified profiles. If you add the "--csv" option the list will be output + as a CSV formatted table +|profile-view +|profile-id +|Dumps a single profile in JSON. The profile-id argument can be retrieved from the `profile-list` command output. +|segment-list +|[--csv] +|Lists all the segments registered in the Apache Unomi server. If you add the "--csv" option the list will be output + as a CSV formatted table +|segment-view +|segment-id +|Dumps a single segment in JSON. The segment-id argument can be retrieved from the `segment-list` command output. +|session-list +|[--csv] +|Lists the last 10 sessions by last event date. If you add the "--csv" option the list will be output + as a CSV formatted table +|session-view +|session-id +|Dumps a single session in JSON. The session-id argument can be retrieved from the `session-list`, `profile-list` or + `event-tail` command output. +|deploy-definition +|[bundleId] [type] [fileName] +|This command can be used to force redeployment of definitions from bundles. By default existing definitions will not +be overriden unless they come from SNAPSHOT bundles. Using this command you can override this mechanism. Here are some +examples of using this command: `unomi:deploy-definition 175 rule *` will redeploy all the rules provided by bundle with id 175. If you launch the command without any arguments you will get prompts for what you want to deploy from which bundle + +|=== \ No newline at end of file
