Command Line Interface (CLI)

Command line interface

This document describes how to use the CLI of OSv.

Including the CLI in the image

The CLI should be included by default. You can also manually add it to the image, with:

$ make image=<your-modules>,cli

Using the CLI

On the guest

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.

On the host

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:

$ 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

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.

Interactive:

$ 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.
$

Ad-hoc:

$ 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

The "api" command

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

Command development

TODO