| // |
| // 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 |
| |[maxEntries] [--csv] |
| |Lists all the rules registered in the Apache Unomi server. The maxEntries (defaults to 100) will allow you to specify |
| how many entries need to be retrieved. If the value is inferior to the total value, a message will display the total |
| value of rules registered in the 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-remove |
| |rule-id |
| |Removes a single rule from Apache Unomi. The `rule-id` argument can be retrieved from the `rule-list` command output. |
| Warning: no confirmation is asked, be careful with this command. |
| |rule-reset-stats |
| |n/a |
| |Resets the rule statistics. This is notably useful when trying to understand rule performance and impact |
| |rule-tail |
| |n/a |
| |Dumps any rule that is executed by the server. Only executed rules are logged here. If you want to have more detailed |
| information about a particular rule's condition evaluation and if it's already been raised use the `rule-watch` command |
| instead. This tail will continue until a CTRL+C key combination is pressed. |
| |rule-watch |
| |rule-ids |
| |Dumps detailed evaluation and execution information about the rules that are where specified in the `rule-ids` arguments |
| (you can specify multiple rule identifiers separated by spaces). The `Status` column has the following values: EVALUATE - |
| indicates that the rule's conditions are being evaluated (but they might not be satisfied), AR PROFILE - means the rule |
| has already been raised for the profile and will therefore not execute again for this profile, AR SESSION - means the |
| rule has already been executed for this session and will therefore only executed when another session for the profile is |
| created, EXECUTE means the rule's actions are being executed. |
| |
| |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. |
| |event-list |
| |[max-entries] [event-type] [--csv] |
| |List the last events processed by Apache Unomi. The `max-entries` parameter can be used to control how many events are |
| displayed (default is 100). The `event-type` makes it possible to filter the list by event type. The `--csv` argument is used to output the list as a CSV list instead of an ASCII table. |
| |event-search |
| |profile-id [event-type] [max-entries] |
| |This command makes it possible to search for the last events by `profile-id` and by `event-type`. A `max-entries` |
| parameter (with a default value of 100) is also accepted to control the number of results returned by the search. |
| |
| |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. |
| |
| |condition-list |
| |[csv] |
| |List all the conditions registered in the server. If you add the "--csv" option the list will be output as a CSV formatted table |
| |condition-view |
| |condition-id |
| |Dumps a single condition in JSON. The condition-id can be retrieved from the `condition-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. |
| |profile-remove |
| |profile-id |
| |Removes a profile identified by `profile-id` argument. Warning: no confirmation is asked so be careful with this command! |
| |
| |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. |
| |segment-remove |
| |segment-id |
| |Removes a single segment identified by the `segment-id` argument. Warning: no confirmation is asked so be careful with |
| this command! |
| |
| |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. |
| If you want to deploy all the definitions of a bundle you can also use wildcards such as in the following example: `deploy-definition 175 * *`. |
| It is also possible to give no argument to this command and it will then interactively request the definitions you want |
| to deploy. |
| |undeploy-definition |
| |[bundleId] [type] [fileName] |
| |This command does the opposite of the `deploy-definition` command and works exactly the same way in terms of arguments |
| and interactive mode except that it undeploys definitions instead of deploying them. This command can be very useful when |
| working on a plugin. For example to remove all the definitions deployed by a plugin you can simply use the following |
| command: `undeploy-definition BUNDLE_ID * *` when `BUNDLE_ID` is the identifier of the bundle that contains your plugin. |
| |
| |=== |