-
-
Notifications
You must be signed in to change notification settings - Fork 606
Command Line Interface (CLI)
This document describes how to use the CLI of OSv.
The CLI should be included by default. You can also manually add it to the image, with:
$ make image=<your-modules>,cli
On the guest the CLI is executed in interactive mode. For a list of commands type: help.
For help with a command type help <command> or <command> --help.
The CLI issues the commands on OSv through its API, so where the CLI is being executed is irrelevant, as long as it has access to the API. To run the CLI on the host, you will first need to build its executable.
First, we need to build Lua and its modules as a dependency for the CLI. If you built the image with the CLI included you can skip this step.
$ cd modules/lua && make
And to build the executable
$ cd modules/cli && make cli
First, one needs to tell the CLI where the API endpoint is, through a command-line parameter:
$ cd modules/cli
$ ./cli --api=http://osv:8000
(osv:8000) stands for your osv vm ip
or an environment variable:
$ cd modules/cli
$ export OSV_API=http://osv:8000
$ ./cli
SSL (https://osv:8000) is also supported, assuming the API is serving HTTPS. For this there are three options:
$ cd modules/cli
$ ./cli --key=client.key --cert=client.pem --cacert=cacert.pem
/# exit
$ # Or through environment variables
$ export OSV_SSL_KEY=client.key
$ export OSV_SSL_CERT=client.pem
$ export OSV_SSL_CACERT=cacert.pem
$ ./cli
/# exit
The CLI has two modes: interactive and ad-hoc. Interactive is like its running on the guest and ad-hoc is for issuing a single command.
$ cd modules/cli
$ ./cli --api=http://osv:8000
/# ls -l /etc
total 6
drwxrwxrwx 4 osv osv 10 Sep 10 12:29 .
drwxrwxrwx 11 osv osv 18 Sep 10 12:35 ..
-rwxrwxrwx 1 osv osv 141 Sep 10 12:29 fstab
-rwxrwxrwx 1 osv osv 30 Sep 10 12:29 hosts
-rwxrwxrwx 1 osv osv 1021 Sep 10 12:29 inputrc
-rwxrwxrwx 0 osv osv 0 Jan 01 1970 mnttab
/# exit
Goodbye.
$
$ cd modules/cli
$ ./cli --api=http://osv:8000 -- ls -l /etc
total 6
drwxrwxrwx 4 osv osv 10 Sep 10 12:29 .
drwxrwxrwx 11 osv osv 18 Sep 10 12:35 ..
-rwxrwxrwx 1 osv osv 141 Sep 10 12:29 fstab
-rwxrwxrwx 1 osv osv 30 Sep 10 12:29 hosts
-rwxrwxrwx 1 osv osv 1021 Sep 10 12:29 inputrc
-rwxrwxrwx 0 osv osv 0 Jan 01 1970 mnttab
$
Note the double-dash, it's so that the cli argument parser wouldn't confuse the command arguments (e.h. -l) for its own.
Ad-hoc mode allows us to use our normal command line utilities along with this CLI. For example:
$ cd modules/cli
$ export OSV_API=http://osv:8000
$ ./cli dmesg | grep foobar
api [OPTION]... API ACTION-WORD [ACTION-WORD]... [PARAMETER=value]...
Options:
-m, --method=[METHOD] The method to use (Default: GET)
-r, --raw Do not process the response
-h Show help of command or sub-command
--help Show this help
api command will translate the REST API definition to a usable command. APIs and resources/actions would be translated to sub-commands. The idea is to have a CLI wrapper around the running API schema for running arbitrary calls. Since this is sort of a RESTful API, actions with side effects (POST, DELETE etc.) will require using a designated flag.
For example, these API calls:
$ curl http://osv:8000/os/version
$ curl http://osv:8000/file/%2fetc%2fhosts?op=GET
$ curl -XPOST http://osv:8000/env/FOO?val=BAR
$ curl -XDELETE http://osv:8000/file/%2fvar%2flog%2ffile?op=DELETE
Will be executed in the CLI like this, respectively:
/# api os version
/# api file /etc/hosts op=GET
/# api -mPOST env FOO val=BAR
/# api -mDELETE /var/log/file op=DELETE
Calling api without arguments will list available APIs:
/# api
API DESCRIPTION
os OS core API
fs FS core API
jvm JVM API
jolokia Jolokia API
file File API
env Environment variables API
trace Trace API
hardware Hardware management API
network Network API
Calling api only with an API will list available sub-commands:
/# api trace
COMMAND DESCRIPTION
trace status All/matching trace event status
[POST] Change all/matching trace event status
trace event {eventid} Trace event info
[POST] Set trace event status
trace count {eventid} [POST] Enable or disable event counting
trace count Get enabled counts
[DELETE] Delete enabled counts
trace sampler [POST] Control sampling profiler
trace buffers Retrieve the trace buffer contents and associated meta data
For a list of operations of a sub-command (API action) parameters, use -h:
/# api -h jvm memory gc
Resource: JVM API
API: /jvm/memory/gc
Operations:
Method: GET
Summary: get GC related information
API: /jvm/memory/gc
Operations:
Method: POST
Summary: Force GC
TODO