Karaf Shell
The Apache Karaf shell console is a powerful, extensible, and Unix-like command-line interface for managing and monitoring the Karaf OSGi container and the Meridian features running within it. It provides a full set of commands for interacting with Meridian, managing services and configurations, and performing administration tasks.
Accessing the Karaf Shell
Accessing the Karaf shell on Meridian is commonly demonstrated as:
ssh -p 8101 admin@localhost
User authentication is performed with the same back-end as the WebUI, however, access to the Karaf shell is limited to users with ROLE_ADMIN.
The Karaf shell accepts ssh connections on a known port which is unique per Meridian component.
| Component | SSH Port |
|---|---|
Meridian Core |
8101 |
Minion |
8201 |
Sentinel |
8301 |
Karaf Shell Commands
If you would like to learn more about an individual command, such as the parameters it accepts, run the command with the --help argument.
All Karaf shell commands output usage information in response to --help.
TAB-completion of commands is both supported and encouraged.
Built-in UNIX-like Commands
This list is not exhaustive; tab-completion in the shell console will show the comprehensive list of all available commands and aliases.
| Command | Description |
|---|---|
shell:alias |
creates an alias to an existing command |
shell:cat |
displays the content of a file or URL |
shell:clear |
clears the current console display |
shell:completion |
displays or change the current completion mode |
shell:date |
displays the current date (optionally using a format) |
shell:each |
executes a closure on a list of arguments |
shell:echo |
echoes and prints arguments to stdout |
shell:edit |
calls a text editor on the current file or URL |
shell:env |
displays or sets the value of a shell session variable |
shell:exec |
executes a system command |
shell:grep |
prints lines matching the given pattern |
shell:head |
displays the first line of the input |
shell:history |
prints the commands history |
shell:if |
allows you to use conditions (if, then, else blocks) in script |
shell:info |
prints various information about the current Karaf instance |
shell:java |
executes a Java application |
shell:less |
a file pager |
shell:logout |
disconnects shell from current session |
shell:more |
a file pager |
shell:new |
creates a new Java object |
shell:printf |
formats and prints arguments |
shell:sleep |
sleeps for a bit then wakes up |
shell:sort |
writes sorted concatenation of all files to stdout |
shell:source |
executes commands contained in a script |
shell:stack-traces-print |
prints the full stack trace in the console when the execution of a command throws an exception |
shell:tac |
captures the STDIN and returns it as a string |
shell:tail |
displays the last lines of the input |
shell:threads |
prints a dump of the current threads |
shell:watch |
periodically executes a command and refresh the output |
shell:wc |
prints newline, words, and byte counts for each file |
shell:while |
loop while the condition is true |
Built-in Bundle Management Commands
An OSGi bundle is a Java archive file that contains Java code, resources, and a manifest that describes the bundle and its dependencies. This list is not exhaustive and only covers the most commonly used commands.
| Command | Description |
|---|---|
bundle:diag |
Displays diagnostic information why a bundle is not Active |
bundle:info |
Displays detailed information of a given bundles |
bundle:install |
Installs one or more bundles |
bundle:list |
Lists all installed bundles |
bundle:refresh |
Refresh bundles |
bundle:requirements |
Displays OSGi requirements of a given bundles |
bundle:resolve |
Resolve bundles |
bundle:restart |
Restarts bundles |
bundle:start |
Starts bundles |
bundle:status |
Get the bundle current status |
bundle:stop |
Stop bundles |
bundle:uninstall |
Uninstall bundles |
bundle:update |
Update bundle |
bundle:watch |
Watches and updates bundles |
Built-in Feature Management Commands
An Apache Karaf feature describes an application as a name, a version, a optional description (eventually with a long description), a set of OSGi bundles, an optional set configurations or configuration files, and an optional set of dependency features.
OPA plugins in Meridian are packaged as Karaf features.
This list is not exhaustive and only covers the most commonly used commands.
| Command | Description |
|---|---|
feature:info |
Shows information about selected feature |
feature:install |
Installs a feature with the specified name and version |
feature:list |
Lists all existing features available from the defined repositories |
feature:refresh |
Reloads features processing instructions and reprovisions existing features |
feature:repo-add |
Add a features repository |
feature:repo-list |
Displays a list of all defined repositories |
feature:repo-refresh |
Refresh a features repository |
feature:repo-remove |
Removes the specified repository features service |
feature:start |
Start features with the specified name and version |
feature:status |
Get the feature’s current status |
feature:stop |
Stop features with the specified name and version |
feature:uninstall |
Uninstalls a feature with the specified name and version |
feature:version-list |
Lists all versions of a feature available from the currently available repositories |
Built-in Configuration Commands
The config commands are frequently used to create or update configuration for Karaf features such as OPA plugins.
This list is not exhaustive and only covers the most commonly used commands.
| Command | Description |
|---|---|
config:cancel |
Cancels the changes to the configuration being edited |
config:delete |
Delete a configuration |
config:edit |
Creates or edits a configuration |
config:exists |
Check if a configuration exists |
config:install |
Install a cfg file in the Karaf etc folder |
config:list |
Lists existing configurations |
config:property-append |
Appends the given value to an existing property or creates the property with the specified name and value |
config:property-delete |
Deletes a property from the configuration being edited |
config:property-get |
Gets the value of a property in the currently edited configuration |
config:property-list |
Lists properties from the currently edited configuration |
config:property-set |
Sets a property in the currently edited configuration |
config:update |
Saves and propagates changes from the configuration being edited |
OpenNMS-provided Commands
| Command | Description | Feature Provided By |
|---|---|---|
device-config:tftp-server-statistics |
View or reset TFTP server statistics |
Enabled By Default |
opennms:activemq-purge-queue |
Purge the content of an ActiveMQ queue |
Enabled By Default |
opennms:activemq-stats |
Show statistics for the embedded ActiveMQ broker |
Enabled By Default |
opennms:alarm-list |
Lists current alarms meeting certain criteria |
Enabled By Default |
opennms:asset-topo-create |
Creates Asset Topology. Uses default config if options are not supplied |
Enabled By Default |
opennms:asset-topo-list |
Lists all of the asset topologies currently installed |
Enabled By Default |
opennms:asset-topo-regenerate |
Regeneates the asset topology for given providerId |
Enabled By Default |
opennms:asset-topo-regenerate-all |
Uses Best Effort to regenerate all asset topologies |
Enabled By Default |
opennms:asset-topo-remove |
Removes Asset Topology. Uses default config if options not supplied |
Enabled By Default |
opennms:bsm-delete-generated-hierarchies |
Deletes generated hierarchies |
Enabled By Default |
opennms:bsm-generate-hierarchies |
Generates hierarchies |
Enabled By Default |
opennms:bsm-render-graph |
Renders the current state machine graph to a .png file |
Enabled By Default |
opennms:classify-flow |
Verify the classification rules by classifying a request |
Enabled By Default |
opennms:collect |
Invokes a collector against a host at a specified location |
Enabled By Default |
opennms:collectd-schedule |
Displays the scheduled data-collection tasks |
Enabled By Default |
opennms:datachoices-display-usage-report |
Displays the usage statistics report |
Enabled By Default |
opennms:datachoices-reset-system-id |
Regenerate the system id |
Enabled By Default |
opennms:datachoices-send-usage-report |
Generate and upload the usage statistics report |
Enabled By Default |
opennms:dcb-get |
Get device config backup from a specific Interface |
Enabled By Default |
opennms:dcb-trigger |
Trigger device config backup from a specific Interface |
Enabled By Default |
opennms:delete-measurement-resource |
Delete the measurements and meta-data for a given resource ID |
Enabled By Default |
opennms:destination-path-trigger |
Trigger test notifications to destination path |
Enabled By Default |
opennms:detect |
Detect the service on a host at specified location |
Enabled By Default |
opennms:dns-lookup |
DNS lookup for the specified host |
Enabled By Default |
opennms:dns-reverse-lookup |
DNS reverse lookup for the specified ipaddress |
Enabled By Default |
opennms:enlinkd-discovery-bridge-domain |
Execute bridge topology discovery algorithm |
|
opennms:enlinkd-reload |
Triggers a restart of the enlinkd daemon |
opennms-enlinkd-shell |
opennms:enlinkd-reload-config |
Triggers a reload of configuration file and restart of the enlinkd daemon |
opennms-enlinkd-shell |
opennms:enlinkd-reload-topology |
Triggers a reload of the topology in case the topology has been updated |
opennms-enlinkd-shell |
opennms:enlinkd-run-collection |
Execute a linkd snmp data collection and persist |
opennms-enlinkd-shell |
opennms:enlinkd-snmp-collect |
Collect enlinkd snmp data |
opennms-enlinkd-shell |
opennms:event |
Show event details for a given id |
Enabled By Default |
opennms:event-list |
Lists historical events meeting certain criteria |
Enabled By Default |
opennms:filter |
Enumerates nodes/interfaces that match a given filter |
Enabled By Default |
opennms:graph-force-reload |
Invalidates the cache for the given container, forcing it to reload when next request occurs |
Enabled By Default |
opennms:graph-get |
Gets a graph identified by its namespace |
Enabled By Default |
opennms:graph-list |
List all available graph containers and its graphs |
Enabled By Default |
opennms:graph-search |
Searches vertices in a given namespace graph |
Enabled By Default |
opennms:health-check |
Verifies that the container is healthy |
Enabled By Default |
opennms:import-requisition |
Sends an 'uei.opennms.org/internal/importer/reloadImport' event to import the requisition from a given url parameter |
Enabled By Default |
opennms:ip-addr-range |
Returns a list of IP addresses in a given range. Useful with closures |
Enabled By Default |
opennms:jira-list-components |
Uses the JIRA ReST API to list all components |
|
opennms:jira-list-fields |
Uses the JIRA ReST API to list all fields available |
jira-troubleticketer |
opennms:jira-list-issue-types |
Uses the JIRA ReST API to list all issue types |
jira-troubleticketer |
opennms:jira-list-priorities |
Uses the JIRA ReST API to list all priorities |
jira-troubleticketer |
opennms:jira-list-projects |
Uses the JIRA ReST API to determine all existing projects |
jira-troubleticketer |
opennms:jira-list-versions |
Uses the JIRA ReST API to list all versions |
jira-troubleticketer |
opennms:jira-show-config |
Shows the current configuration for the Jira Ticketer Plugin |
jira-troubleticketer |
opennms:jira-verify |
Verifies the current configuration |
jira-troubleticketer |
opennms:kafka-evaluate-filter |
Compiles the given expression and optionally test it against an object |
|
opennms:kafka-push-topology-edges |
Pushes all of the related topology edges to the configured topic |
opennms-kafka-producer |
opennms:kafka-sink-topics |
List Sink Topics used by current system |
opennms-core-ipc-kafka |
opennms:kafka-list-alarms |
Enumerates the alarms that are currently in the Kafka data store |
opennms-kafka-producer |
opennms:kafka-rpc-topics |
List RPC topics used by current system |
opennms-core-ipc-kafka |
opennms:kafka-sync-alarms |
Triggers a syncrhonization of the alarms topic against the database |
opennms-kafka-producer |
opennms:kv-benchmark-blob |
Benchmark the blob store’s throughput |
Enabled By Default |
opennms:kv-get-blob |
Get a record from the blob store decoded as a string |
Enabled By Default |
opennms:kv-get-json |
Get a record from the JSON store |
Enabled By Default |
opennms:kv-put-blob |
Insert a string record into the blob store |
Enabled By Default |
opennms:kv-put-json |
Insert a record into the JSON store |
Enabled By Default |
opennms:list-classification-groups |
Lists all classification groups stored in the database |
Enabled By Default |
opennms:list-classification-invalid-rules |
Lists invalid classification rules |
Enabled By Default |
opennms:list-classification-rules |
Lists classification rules stored in the database |
Enabled By Default |
opennms:list-collectors |
Lists all of the available collectors |
Enabled By Default |
opennms:list-detectors |
Lists all of the available detectors |
Enabled By Default |
opennms:list-monitors |
Lists all of the available monitors |
Enabled By Default |
opennms:list-namespaces |
Lists the available blueprint namespaces and their providers |
org.opennms.features.topology.shell |
opennms:metadata-test |
Test Meta-Data replacement |
Enabled By Default |
opennms:metrics-display |
Display metrics from one or more metric sets |
Enabled By Default |
opennms:metrics-list |
List the available metric sets |
Enabled By Default |
opennms:ping |
ICMP Ping |
Enabled By Default |
opennms:ping-sweep |
ICMP Ping Sweep |
Enabled By Default |
opennms:poll |
Used to invoke a monitor against a host at a specific location, or to test a service monitor definition from a given poller package |
Enabled By Default |
opennms:poller-benchmark |
Benchmark pollerd by creating N nodes/services and waiting for them to be polled |
Enabled By Default |
opennms:pollerd-schedule |
Displays the scheduled poller tasks |
Enabled By Default |
opennms:reload-classification-engine |
Reloads the rules of the classification engine |
Enabled By Default |
opennms:reload-daemon |
Reload a specific daemon |
Enabled By Default |
opennms:scv-delete |
Delete the stored credentials for the given alias |
Enabled By Default |
opennms:scv-get |
Retrieves the username and attributes for the given alias |
Enabled By Default |
opennms:scv-list |
List the available aliases |
Enabled By Default |
opennms:scv-set |
Sets and securely store the credentials for the given alias |
Enabled By Default |
opennms:scv-validate |
validate credentials for the given alias |
Enabled By Default |
opennms:send-event |
Send event with specified uei and params |
Enabled By Default |
opennms:show-event-config |
Renders the matched event definitions to XML. This command makes it possible to view event definitions which are not serialized on disk |
Enabled By Default |
opennms:show-import |
Display the resulting requisition generated by a given URL |
Enabled By Default |
opennms:show-measurement-resources |
Displays the resource tree. Optionally filter by node or resource ID |
Enabled By Default |
opennms:show-measurements |
Measurements |
Enabled By Default |
opennms:show-newts-samples |
Show the raw sample stored in Newts |
Enabled By Default |
opennms:snmp-config-decrypt |
Decrypts snmp config and saves it on file system as a separate file |
Enabled By Default |
opennms:snmp-config-encrypt |
Encrypts snmp config and saves it on file system |
Enabled By Default |
opennms:snmp-fit |
Fit a profile for a given IP address |
Enabled By Default |
opennms:snmp-get |
Request one or more fully-qualified MIB objects from the agent on the specified host and print the results |
Enabled By Default |
opennms:snmp-local-engine-id |
Display the Local Engine Id used for Traps/Informs |
Enabled By Default |
opennms:snmp-metadata-provisioning-adapter |
Trigger SnmpMetadataProvisioningAdapter for a set of nodes |
Enabled By Default |
opennms:snmp-remove-from-definition |
Remove an IP address from a definition |
Enabled By Default |
opennms:snmp-show-config |
Display the effective SNMP agent configuration |
Enabled By Default |
opennms:snmp-walk |
Walk one or more MIB objects from the agent on the specified host and print the results |
Enabled By Default |
opennms:stress-dns |
Stress the DNS lookups |
Enabled By Default |
opennms:stress-events |
Stress the event bus with generated events |
Enabled By Default |
opennms:stress-metrics |
Stress the current persistence strategy with generated collection sets |
Enabled By Default |
opennms:stress-rpc |
Generates RPC requests against the Echo module |
Enabled By Default |
opennms:telemetry-listeners |
Lists configured telemetry listeners |
Enabled By Default |
opennms:telemetry-parsers |
Lists configured telemetry parsers |
Enabled By Default |
opennms:telemetry-replay-pcap |
Replay a packet capture directly to a UDP-based parser |
Enabled By Default |
opennms:threshold-clear |
Clears a specific threshold state |
Enabled By Default |
opennms:threshold-clear-all |
Clears all threshold states |
Enabled By Default |
opennms:threshold-details |
Prints the details of a specific threshold state |
Enabled By Default |
opennms:threshold-enumerate |
Enumerates threshold states |
Enabled By Default |
opennms:topo-delete-history |
Deletes history of all users |
org.opennms.features.topology.shell |
opennms:topo-list-operations |
Lists the available OpenNMS topology operations |
org.opennms.features.topology.shell |
opennms:topo-show-history |
Shows the history of a certain user |
org.opennms.features.topology.shell |
opennms:track-service |
Track services that match a given filter |
Enabled By Default |
opennms:ts-stats |
Prints statistics about the timeseries integration layer |
|
opennms:twin-subscribe |
Get current Twin Object for the key specified |
Enabled By Default |
External Documentation
Documentation on Karaf and its features, including the Karaf shell interface, is maintained by the Apache Software Foundation and can be found at https://karaf.apache.org/manual/latest/