wip: adding cli tool #8

gaohoward · 2024-09-11T10:41:03Z

Jolokia api-server Cli tool (work in progress)

The Jolokia api-server comes with a cli (command line interface) tool. When the cli tool starts it connects to the api-server and can access the jolokia endpoints.

The cli tool takes a command and requests the api-server using its api to invoke on the target jolokia endpint, gets back the response and printing the result to the console in JSON format.

It can run in interactive mode or in non-interactive mode.

To build the cli tool run

yarn build

which will build both the api-server and cli tool.

To install the cli tool runnable locally run:

npm link

It will create the cli runnable jolokia-api-server-cli

Running the cli tool

The cli tool needs a running api-server.

To start the cli tool run

jolokia-api-server-cli [options]

or you can use yarn

yarn start-cli [options]

Using Cli tool in non-interactive mode

In this mode, the tool starts and execute a command and then exits.

The syntax for non-interactive mode is:

jolokia-api-server-cli <command> -l <api-server-url> -e <jolokia-endpoint-url>

If -l option is omitted the default is https://localhost:9443

The -e option is the target jolokia url. for example

-e http://user:password@127.0.0.1:8161

If the port number part is omitted, the default
is 80 for http and 443 for https.

The command is the command to be executed.

Note in non-interactive mode the command need be quoted if

the command contains options (e.g -e) because the '-' can be interpreted by the shell
the command contains '*' char

Example:

jolokia-api-server-cli "get queue TEST -a MessageCount RoutingType" -e http://user:pass@127.0.0.1:8161

Alternatively you can use -- to separate the command:

jolokia-api-server-cli -e http://user:pass@127.0.0.1:8161 -- get @broker2/queue DLQ -a MessageCount

Using Cli tool in interactive mode

In interactive mode the tool starts into a command shell and
accepts user input as a command, then it executes it and went
back to the shell prompt to accept another, until you run the exit
command.

The syntax to run the cli in this mode is

jolokia-api-server-cli -i

When it starts it print the cli title and ready to accept
commands.

With interactive mode the cli can 'caches' a list of jolokia endpoints (added by the add command
only available in interactive mode). It takes one of them as current endpoint so when user types
a command without specifying target jolokia endpoint, the current endpoint will be used.

Using Cli Commands

The `get` command

This is the only available command currently. It can retrive
information from a jolokia endpoint.

The syntax of this command is

get <path> <name> <-a attributes...> <-o operations...>

It takes a path argument, a name argument, an optional -a(attribute) option and an optional
-o (operation) option.

The value of path is a string representing a target mbean from which you want to get information.
It takes the form [target endpoint]/[component]. The target endpoint in interactive mode allows
you to specify which broker you want to retrieve information from. If absent it takes the current broker
cached by the cli. In non-interactive mode that [target endpoint] can be empty if -e option is given,
or it is the target remote endpoint name prefix by a @ char. For example @broker1/

The component part is the type of the mbean. Currently the supported mbean types are

queue
address
acceptor
cluster-connection

NOTE

If the target component is the broker itself, the component should be left empty. For example

get @broker1/ -a Status

It means to get the value of Status attribute of the broker.

The argument is the mbean name (e.g. DLQ, testQueue, etc).

The value of -a option is a list of attribute names (space or comma separated) to read from the target mbean.
If the value is a * it will read all the attributes of the target mbean.

The value of -o option is a list of operation names (space or comma separated) to read from the target mbean.
If the value is a * it will read all the operations of the target mbean.

examples:

get @broker1/ - get the current broker mbean information

get @broker1/* - get all mbeans registered with the broker mbean

get @broker1/ -a * - read all the attributes of the broker mbean

get @broker1/ -a * -o * - read information of all attributes and operations of the broker mbean

get @broker1/queue (or get /queue) - list all the queue mbeans information

get @broker1/acceptor acceptor0 -a * - read all attributes of acceptor named acceptor0

get @broker1/queue TEST -a MessageCount RoutingType - read MessageCount and RoutingType of queue TEST

get @broker1/queue -o xxx - read information of operation xxx of queue TEST

The `run` command

The run command is used to invoke operations on a jolokia endpoint.

The syntax of this command is

run <path> <name> <operation>

It takes a path argument, a name argument and an operation to be executed on the mbean.
The syntax for path and name are the same as for the get command.

The operation takes the form ([args...]). For example

run @broker1/ listAddresses(m)

It means to call listAddresses(java.lang.String) method on @broker1 with argument value 'm'.

Commands exclusive to Interactive mode

There are several commands that are only available to interactive mode.

The `add` command

Add a jolokia endpoint to the cli cache. Syntax:

add <endpoint name> <url> -u <user> -p <password>

example:

add ex-aao-ssl https://ex-aao-ssl-wconsj-0-svc-rte-default.apps-crc.testing -u user -p password

This command allows user to add a jolokia endpoint that is not managed by the api-server. After the
endpoint is added the user can access the endpoint using the cli commands.

NOTE

When accessing such jolokia endpoints, the command references it without @ prefixed, for example

get ex-aao-ssl/ -a Status

The `switch` command

To change current endpoint. Syntax:

switch <endpoint name>

example:

switch broker0

A command can be simplified if it is targeted at the current endpoint. For example if you
set the current endpoint to broker0 the command

> add broker0 http://127.0.0.2:8161 -u guest -p guest

and if you want to get the queues of the broker0, you can do

get /queues

instead of explicitly:

get broker0/queues

The `list` command

To list all the jolokia endpoints cached in cli and managed on the api-server. Syntax:

> list
[
  "local2(local): http://127.0.0.2:8161",
  "@pod-0: https://broker-pem-wconsj-0-svc-ing-default.artemiscloud.io:443",
  "@pod-1: https://broker-pem-wconsj-1-svc-ing-default.artemiscloud.io:443",
  "@local: http://127.0.0.1:8161",
  "@restricted: https://artemis-broker-jolokia-0-svc-ing-default.artemiscloud.io:443"
]

lavocatt

Nice work @howardgao! Here are a few pieces of feedback:

When I'm running the executable without any arguments I'm getting this error:

Maybe instead of erroring out it could display the help?

When I'm in interactive mode, I would appreciate having help when requesting some from the tool

It is slightly confusing that the command needs to get in quotes on the command line, ie it doesn't understand get / but does get 'get /'

gaohoward · 2024-09-11T14:10:15Z

@lavocatt Thanks Thomas for trying it out! I think all your points make sense. The help system is bad. I'll improve it.

src/cli/index.ts

src/cli/context.ts

src/utils/security_util.ts

src/cli/index.ts

lavocatt · 2024-11-27T07:51:22Z

Small comment, I think this PR shouldn't have to embed a commit related to the security model as its principal matter of concern is about adding the CLI tool.

gaohoward · 2024-11-27T09:26:38Z

Small comment, I think this PR shouldn't have to embed a commit related to the security model as its principal matter of concern is about adding the CLI tool.

Yes you are right. As it is a draft right now I included the security model to test cli's login to api server. Once the security model is merged I'll rebase the PR.

The API Server provides a security model that provides authentication and authorization of incoming clients. The security can be enabled/disabled (i.e. via `API_SERVER_SECURITY_ENABLED` env var) Currently the api server support `jwt` token authentication. The login api is defined in openapi.yml /server/login A client logs in to an api server by sending a POST request to the login path. The request body contains login information (i.e. username and password for jwt authentication type) Please refer to [api.md](api.md) for details of the login api. Currently the security manager uses local file to store user's info. The default users file name is `.users.json` The users file name can be configured using `USERS_FILE_URL` env var. See `.test.users.json` for sample values. Currently the api server doesn't perform authorization on logged in users. The server keeps a list of jolokia endpoints for clients to access. The endpoints are loaded from a local file named `.endpoints.json`. Each top level entry represents a jolokia endpoint. An entry has a unique name and details to access the jolokia api. See `.test.endpoints.json` for sample values. When an authenticated client sends a request to the api-server, it should present its token in the request header 'Authorization: Bearer `token`' It also need to give the `targetEndpoint` in the query part of the request if the request is to access an jolokia endpoint. For example `/execBrokerOperation?targetEndpoint=broker1`. Direct Proxy means a client can pass a broker's endpoint info to the api-server in order to access it via the api-server. For example the [self-provisioning plugin] (https://github.com/artemiscloud/activemq-artemis-self-provisioning-plugin) uses this api to access the jolokia of a broker's jolokia endpoint.

@broker1

The Jolokia api-server comes with a cli (command line interface) tool. When the cli tool starts it connects to the api-server and can access the jolokia endpoints. The cli tool takes a **command** and requests the api-server using [its api](src/config/openapi.yml) to invoke on the target jolokia endpint, gets back the response and printing the result to the console in JSON format. It can run in `interactive mode` or in `non-interactive` mode. To build the cli tool run ``` yarn build ``` which will build both the api-server and cli tool. To install the cli tool runnable locally run: ``` npm link ``` It will create the cli runnable `jolokia-api-server-cli` The cli tool needs a running api-server. To start the cli tool run ``` jolokia-api-server-cli [options] ``` or you can use `yarn` ``` yarn start-cli [options] ``` In this mode, the tool starts and execute a command and then exits. The syntax for non-interactive mode is: ``` jolokia-api-server-cli <command> -l <api-server-url> -e <jolokia-endpoint-url> ``` If `-l` option is omitted the default is ` https://localhost:9443` The `-e` option is the target jolokia url. for example ``` -e http://user:password@127.0.0.1:8161 ``` If the port number part is omitted, the default is `80` for http and `443` for https. The `command` is the command to be executed. Note in non-interactive mode the `command` need be quoted if 1. the command contains options (e.g -e) because the '-' can be interpreted by the shell 2. the command contains '*' char Example: ``` jolokia-api-server-cli "get queue TEST -a MessageCount RoutingType" -e http://user:pass@127.0.0.1:8161 ``` Alternatively you can use `--` to separate the command: ``` jolokia-api-server-cli -e http://user:pass@127.0.0.1:8161 -- get @broker2/queue DLQ -a MessageCount ``` In interactive mode the tool starts into a command shell and accepts user input as a command, then it executes it and went back to the shell prompt to accept another, until you run the `exit` command. The syntax to run the cli in this mode is ``` jolokia-api-server-cli -i ``` When it starts it print the cli title and ready to accept commands. With interactive mode the cli can 'caches' a list of jolokia endpoints (added by the `add` command only available in interactive mode). It takes one of them as `current endpoint` so when user types a command without specifying target jolokia endpoint, the `current endpoint` will be used. This is the only available command currently. It can retrive information from a jolokia endpoint. The syntax of this command is ``` get <path> <name> <-a attributes...> <-o operations...> ``` It takes a `path` argument, a `name` argument, an optional `-a`(attribute) option and an optional `-o` (operation) option. The value of `path` is a string representing a target mbean from which you want to get information. It takes the form [target endpoint]/[component]. The `target endpoint` in `interactive` mode allows you to specify which broker you want to retrieve information from. If absent it takes the current broker cached by the cli. In non-interactive mode that [target endpoint] can be empty if `-e` option is given, or it is the target remote endpoint name prefix by a `@` char. For example `@broker1/` The `component` part is the type of the mbean. Currently the supported mbean types are - `queue` - `address` - `acceptor` - `cluster-connection` --- **NOTE** If the target component is the broker itself, the component should be left empty. For example `get @broker1/ -a Status` It means to get the value of `Status` attribute of the broker. --- The <name> argument is the mbean name (e.g. DLQ, testQueue, etc). The value of `-a` option is a list of attribute names (space or comma separated) to read from the target mbean. If the value is a `*` it will read all the attributes of the target mbean. The value of `-o` option is a list of operation names (space or comma separated) to read from the target mbean. If the value is a `*` it will read all the operations of the target mbean. examples: `get @broker1/` - get the current broker mbean information `get @broker1/*` - get all mbeans registered with the broker mbean `get @broker1/ -a *` - read all the attributes of the broker mbean `get @broker1/ -a * -o *` - read information of all attributes and operations of the broker mbean `get @broker1/queue` (or `get /queue`) - list all the queue mbeans information `get @broker1/acceptor acceptor0 -a *` - read all attributes of acceptor named `acceptor0` `get @broker1/queue TEST -a MessageCount RoutingType` - read `MessageCount` and `RoutingType` of queue `TEST` `get @broker1/queue -o xxx` - read information of operation xxx of queue TEST The `run` command is used to invoke operations on a jolokia endpoint. The syntax of this command is ``` run <path> <name> <operation> ``` It takes a `path` argument, a `name` argument and an `operation` to be executed on the mbean. The syntax for `path` and `name` are the same as for the `get` command. The operation takes the form <operation-name>([args...]). For example ``` run @broker1/ listAddresses(m) ``` It means to call listAddresses(java.lang.String) method on @broker1 with argument value 'm'. There are several commands that are only available to interactive mode. Add a jolokia endpoint to the cli cache. Syntax: ``` add <endpoint name> <url> -u <user> -p <password> ``` example: ``` add ex-aao-ssl https://ex-aao-ssl-wconsj-0-svc-rte-default.apps-crc.testing -u user -p password ``` This command allows user to add a jolokia endpoint that is not managed by the api-server. After the endpoint is added the user can access the endpoint using the cli commands. --- **NOTE** When accessing such jolokia endpoints, the command references it without `@` prefixed, for example `get ex-aao-ssl/ -a Status` --- To change `current endpoint`. Syntax: ``` switch <endpoint name> ``` example: ``` switch broker0 ``` A command can be simplified if it is targeted at the current endpoint. For example if you set the current endpoint to `broker0` the command ``` > add broker0 http://127.0.0.2:8161 -u guest -p guest ``` and if you want to get the queues of the broker0, you can do ``` get /queues ``` instead of explicitly: ``` get broker0/queues ``` To list all the jolokia endpoints cached in cli and managed on the api-server. Syntax: ``` > list [ "local2(local): http://127.0.0.2:8161", "@pod-0: https://broker-pem-wconsj-0-svc-ing-default.artemiscloud.io:443", "@pod-1: https://broker-pem-wconsj-1-svc-ing-default.artemiscloud.io:443", "@Local: http://127.0.0.1:8161", "@restricted: https://artemis-broker-jolokia-0-svc-ing-default.artemiscloud.io:443" ] ```

gaohoward requested review from lavocatt, ajaypratap003, AjayJagan and Msarawan September 11, 2024 10:42

lavocatt reviewed Sep 11, 2024

View reviewed changes

gaohoward requested a review from lavocatt September 24, 2024 03:48

github-advanced-security bot found potential problems Sep 24, 2024

View reviewed changes

src/cli/index.ts Fixed Show resolved Hide resolved

gaohoward force-pushed the c_add_cli branch 4 times, most recently from b7bf9f7 to 88b2a1a Compare October 22, 2024 11:53

github-advanced-security bot found potential problems Oct 22, 2024

View reviewed changes

src/cli/context.ts Fixed Show fixed Hide fixed

gaohoward force-pushed the c_add_cli branch 3 times, most recently from 3624e22 to ccd61e1 Compare October 28, 2024 16:00

gaohoward force-pushed the c_add_cli branch from ccd61e1 to de83a64 Compare October 30, 2024 15:21

github-advanced-security bot found potential problems Oct 30, 2024

View reviewed changes

src/utils/security_util.ts Fixed Show fixed Hide fixed

src/utils/security_util.ts Dismissed Show dismissed Hide dismissed

gaohoward force-pushed the c_add_cli branch 2 times, most recently from 691dd0a to da8134c Compare November 4, 2024 11:36

gaohoward force-pushed the c_add_cli branch from da8134c to 601e62e Compare November 20, 2024 03:49

github-advanced-security bot found potential problems Nov 20, 2024

View reviewed changes

src/cli/index.ts Dismissed Show dismissed Hide dismissed

gaohoward force-pushed the c_add_cli branch 3 times, most recently from 3ee6c1f to c1017da Compare November 27, 2024 03:53

gaohoward force-pushed the c_add_cli branch 3 times, most recently from 4d2cabc to 88847cb Compare November 27, 2024 14:32

gaohoward force-pushed the c_add_cli branch from 88847cb to c58f464 Compare December 3, 2024 02:30

gaohoward force-pushed the c_add_cli branch from c58f464 to 7b00703 Compare December 3, 2024 02:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

wip: adding cli tool #8

wip: adding cli tool #8

gaohoward commented Sep 11, 2024 •

edited

Loading

lavocatt left a comment •

edited

Loading

gaohoward commented Sep 11, 2024

lavocatt commented Nov 27, 2024

gaohoward commented Nov 27, 2024

wip: adding cli tool #8

Are you sure you want to change the base?

wip: adding cli tool #8

Conversation

gaohoward commented Sep 11, 2024 • edited Loading

Jolokia api-server Cli tool (work in progress)

Running the cli tool

Using Cli tool in non-interactive mode

Using Cli tool in interactive mode

Using Cli Commands

The get command

The run command

Commands exclusive to Interactive mode

The add command

The switch command

The list command

lavocatt left a comment • edited Loading

Choose a reason for hiding this comment

gaohoward commented Sep 11, 2024

lavocatt commented Nov 27, 2024

gaohoward commented Nov 27, 2024

gaohoward commented Sep 11, 2024 •

edited

Loading

The `get` command

The `run` command

The `add` command

The `switch` command

The `list` command

lavocatt left a comment •

edited

Loading