Skip to content

Latest commit

 

History

History
282 lines (208 loc) · 8.74 KB

CLI.md

File metadata and controls

282 lines (208 loc) · 8.74 KB
Raw

CLI Reference

Here we describe Capstan CLI in detail. Please note that this very same information can be obtained by adding --help flag to any of the listed commands.

Working with application packages

These commands are useful when packaging my application into Capstan package.

capstan package init

NAME:
   capstan package init - initialise package structure

USAGE:
   capstan package init [command options] [path]

OPTIONS:
   --name value, -n value      package name
   --title value, -t value     package title
   --author value, -a value    package author
   --version value, -v value   package version
   --require value             specify package dependency
   --runtime value             runtime to stub package for. Use 'capstan runtime list' to list all
   -p value, --platform value  platform where package was built on

capstan package collect

NAME:
   capstan package collect - collects contents of this package and all required packages

USAGE:
   capstan package collect [command options] [arguments...]

OPTIONS:
   --pull-missing, -p  attempt to pull packages missing from a local repository
   --boot value        specify config_set name to boot unikernel with
   --verbose, -v       verbose mode

capstan package compose

NAME:
   capstan package compose - composes the package and all its dependencies into OSv image

USAGE:
   capstan package compose [command options] image-name

OPTIONS:
   --size value, -s value  total size of the target image (use M or G suffix) (default: "10G")
   --update                updates the existing target VM by uploading only modified files
   --verbose, -v           verbose mode
   --run value             the command line to be executed in the VM
   --pull-missing, -p      attempt to pull packages missing from a local repository
   --boot value            specify default config_set name to boot unikernel with
   --env value             specify value of environment variable e.g. PORT=8000 (repeatable)

Integrating existing packages

These commands are useful when we intend to use package from remote repository.

capstan package list

NAME:
   capstan package list - lists the available packages

USAGE:
   capstan package list [arguments...]

capstan package search

NAME:
   capstan package search - searches for packages in the remote repository (partial name matches are also supported)

USAGE:
   capstan package search [package-name]

capstan package pull

NAME:
   capstan package pull - pulls the package from remote repository and imports it into local package storage

USAGE:
   capstan package pull [package-name]

Working with runtimes

Runtime-related commands.

capstan runtime list

NAME:
   capstan runtime list - list available runtimes

USAGE:
   capstan runtime list [arguments...]

capstan runtime preview

NAME:
   capstan runtime preview - prints runtime yaml template to the console

USAGE:
   capstan runtime preview [command options] [arguments...]

OPTIONS:
   --runtime value, -r value  Runtime name. Use 'capstan runtime list' to see available names.
   --plain                    Remove comments

capstan runtime init

NAME:
   capstan runtime init - prepares meta/run.yaml stub for selected runtime

USAGE:
   capstan runtime init [command options] [arguments...]

OPTIONS:
   --runtime value, -r value  Runtime name. Use 'capstan runtime list' to see available names.
   --plain                    Remove comments
   --force, -f                Override existing meta/run.yaml

Executing unikernel

Commands used to run composed package.

capstan run

NAME:
   capstan run - launch a VM. You may pass the image name as the first argument.

USAGE:
   capstan run [command options] instance-name

OPTIONS:
   -i value                   image_name
   -p value                   hypervisor: qemu|vbox|vmw|gce (default: "qemu")
   -m value                   memory size (default: "1G")
   -c value                   number of CPUs (default: 2)
   -n value                   networking: nat|bridge|tap|vhost (default: "nat")
   -v                         verbose mode
   -b value                   networking device (bridge or tap): e.g., virbr0, vboxnet0, tap0
   -f value                   port forwarding rules
   --gce-upload-dir value     Directory to upload local image to: e.g., gs://osvimg
   --mac value                MAC address. If not specified, the MAC address will be generated automatically.
   --execute value, -e value  set the command line to execute
   --boot value               specify config_set name to boot unikernel with
   --persist                  persist instance parameters (only relevant for qemu instances)
   --env value                specify value of environment variable e.g. PORT=8000 (repeatable)
   --volume value             {path}[:{key=val}], e.g. ./volume.img:format=raw (repeatable)
                                    Default options are :format=raw:aio=native:cache=none

Executing unikernel on OpenStack

Commands used to compose unikernel, upload it to OpenStack Glance and run it with OpenStack Nova.

capstan stack push

NAME:
   capstan stack push - composes OSv image and pushes it to OpenStack

USAGE:
   capstan stack push [command options] image-name

DESCRIPTION:
   Compose package, build .qcow2 image and upload it to OpenStack under nickname <image-name>.

OPTIONS:
   --size value, -s value    minimal size of the target user partition (use M or G suffix).
                             NOTE: will be enlarged to match flavor size. (default: "10G")
   --flavor value, -f value  OpenStack flavor name that created OSv image should fit to
   --run value               the command line to be executed in the VM
   --keep-image              don't delete local composed image in .capstan/repository/stack
   --verbose, -v             verbose mode
   --pull-missing, -p        attempt to pull packages missing from a local repository
   --boot value              specify config_set name to boot unikernel with
   --env value               specify value of environment variable e.g. PORT=8000 (repeatable)
   --OS_AUTH_URL value       OpenStack auth url (e.g. http://10.0.2.15:5000/v2.0)
   --OS_TENANT_ID value      OpenStack tenant id (e.g. 3dfe7bf545ff4885a3912a92a4a5f8e0)
   --OS_TENANT_NAME value    OpenStack tenant name (e.g. admin)
   --OS_PROJECT_NAME value   OpenStack project name (e.g. admin)
   --OS_USERNAME value       OpenStack username (e.g. admin)
   --OS_PASSWORD value       OpenStack password (*TODO*: leave blank to be prompted)
   --OS_REGION_NAME value    OpenStack username (e.g. RegionOne)

capstan stack run

NAME:
   capstan stack run - runs image that was previously pushed to OpenStack

USAGE:
   capstan stack run [command options] image-name

DESCRIPTION:
   Run image that you've previously uploaded with 'capstan stack push'.
   Please note that image size CANNOT be changed at this point (wont' boot on
   too small flavor, wont use extra space on too big flavor), but feel free
   to adjust amount of memory (RAM).

OPTIONS:
   --flavor value, -f value  OpenStack flavor to be run with
   --mem value, -m value     MB of memory (RAM) to be run with
   --name value, -n value    instance name
   --count value, -c value   number of instances to run (default: 1)
   --verbose, -v             verbose mode
   --OS_AUTH_URL value       OpenStack auth url (e.g. http://10.0.2.15:5000/v2.0)
   --OS_TENANT_ID value      OpenStack tenant id (e.g. 3dfe7bf545ff4885a3912a92a4a5f8e0)
   --OS_TENANT_NAME value    OpenStack tenant name (e.g. admin)
   --OS_PROJECT_NAME value   OpenStack project name (e.g. admin)
   --OS_USERNAME value       OpenStack username (e.g. admin)
   --OS_PASSWORD value       OpenStack password (*TODO*: leave blank to be prompted)
   --OS_REGION_NAME value    OpenStack username (e.g. RegionOne)

Configuring Capstan tool

Commands used to configure Capstan.

capstan config print

NAME:
   capstan config print - print current capstan configuration

USAGE:
   capstan config print [arguments...]

Contextualizing unikernel remotely

Commands used to contextualize remote unikernel (i.e. on OpenStack Glance).

capstan package compose-remote

NAME:
   capstan package compose-remote - composes the package and all its dependencies and uploads resulting files into remote OSv instance

USAGE:
   capstan package compose-remote [command options] remote-instance

OPTIONS:
   --verbose, -v       verbose mode
   --pull-missing, -p  attempt to pull packages missing from a local repository

Documentation compiled on: 2017/12/18 07:08
capstan version 'v0.2.1-66-g4248dd0'