ops - build and run nanos unikernels

Last update: Jan 9, 2023

Overview

OPS

Ops is a tool for creating and running a Nanos unikernel. It is used to package, create and run your application as a nanos unikernel instance.

Check out the DOCS

Installation

Most users should just download the binary from the website:

Binary install

curl https://ops.city/get.sh -sSfL | sh

Build and Install from source

Building from source is easy if you have used Go before.

This program requires GO Version 1.13.x or greater.

Installing from source follows these general steps:

Install dependencies:

make deps

Build:

make build

osx notes:

GO111MODULE=on go build -ldflags "-w"

For detailed instructions please consult the documentation.

Basic usage examples

Before learning more about ops it is a good idea to see some basic usage examples. Below are links to simple examples using various programming platforms:

Let's run your first unikernel right now.

Throw this into hi.js:

var http = require('http');
http.createServer(function (req, res) {
    res.writeHead(200, {'Content-Type': 'text/plain'});
    res.end('Hello World\n');
}).listen(8083, "0.0.0.0");
console.log('Server running at http://127.0.0.1:8083/');

Then you can run it like so:

ops pkg load node_v11.5.0 -p 8083 -f -n -a hi.js

Want to push your app out to the cloud?

For Google: https://nanovms.gitbook.io/ops/google_cloud

For AWS: https://nanovms.gitbook.io/ops/aws

Languages:

Applications:

Nginx
HAProxy
Tarantool
Hiawatha
Mosquitto
Kache
Gnatsd
Wasmer

You can always find more pre-made packages via:

ops pkg list

Build a bootable image

ops build <app>

Package and run

ops run <app>
# or
ops run -p <port> <app>

Using a config file

ops run -p <port> -c <file> <app>

Example config file

ops config files are plain JSON, below is an example

{
  "Args":["one","two"],
  "Dirs":["myapp/static"]
}

Setup networking

New users wishing to play around in a dev environment are encouraged to use the default user-mode networking. Other production users are encouraged to utilize native cloud builds such as Google Cloud which handle networking for you.

Only advanced/power users should use the bridge networking option.

Reporting Bugs

Feel free to open up a pull request. It's helpful to have your OPS version and the release channel you are using.

Also - if it doesn't work on the main release you can try the nightly - the main release can tail the nightly by many weeks sometimes.

ops version

get the release channel (or nightly)

ls .ops/

if using a package get the package hash:

cat .ops/packages/manifest.json| jq '."gnatsd_1.4.1"'

Pull Requests

If you have an idea for a new feature and it might take longer than a few hours or days to do it's worth opening a feature request tkt to ideate it first before jumping into code. There might be someone already working on the feature or plans to do something entirely different.

Security

Feel free to email security at.

Support

If you are having trouble running a particular application please feel free to open an issue and we can take a look. In general we'll only want to support the latest release from a given application/project, however if you really want/need support for something older there are paid support plans available - contact the folks at https://nanovms.com .

Comments

Issues Creating a Local Dev Package: Dartlang v2.10.4

Hello! I am currently working my way through the documentation and was trying to create a new local development package containing Dartlang v2.10.4, but I seem to be running into a lot of error messages.

I used the following links as reference points for building the package:

https://nanovms.gitbook.io/ops/packages#creating-a-custom-or-local-dev-packages
https://github.com/nanovms/ops/blob/master/PACKAGES.md

My steps for creating the package were as follows:

Create a new directory: mkdir dart_2.10.4
Add the dart binary from the downloaded dartsdk-linux-x64-release.zip (found in dart-sdk/bin)
Create a package.manifest file:

{
    "Program": "dart_2.10.4/dart",
    "Args": ["dart"],
    "Version": "2.10.4"
}

Use ldd dart to find the shared libraries and copy these over to sub-folders within dart_2.10.4/sysroot:

fredrikbakken@pop-os:~/Documents/github/unikernels/pkgs$ ldd dart_2.10.4/dart
        linux-vdso.so.1 (0x00007ffcbd9e6000)
        libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007fe5392d9000)
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fe5392b7000)
        libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fe539168000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fe538f7e000)
        /lib64/ld-linux-x86-64.so.2 (0x00007fe53b661000)

My tree structure now looks like this:

fredrikbakken@pop-os:~/Documents/github/unikernels/pkgs$ tree dart_2.10.4
dart_2.10.4
├── dart
├── package.manifest
└── sysroot
    ├── lib
    │   └── x86_64-linux-gnu
    │       ├── libc.so.6
    │       ├── libdl.so.2
    │       ├── libm.so.6
    │       ├── libnss_dns.so.2
    │       ├── libpthread.so.0
    │       └── libresolv.so.2
    └── lib64
        └── ld-linux-x86-64.so.2

4 directories, 9 files

Copy the dart_2.10.4 directory to ~/.ops/local_packages: cp -r ./dart_2.10.4 ~/.ops/local_packages/dart_2.10.4/
Create an example application (main.dart):

void main() {
	print("Hello world!");
}

Use ops with the local dart_2.10.4 package to run the example file: ops load -l dart_2.10.4 -a main.dart

The error message I keep running into:

fredrikbakken@pop-os:~/Documents/github/unikernels/pkgs$ ops load -l dart_2.10.4 -a main.dart -v
[dart main.dart]
booting /home/fredrikbakken/.ops/images/dart.img ...
qemu-system-x86_64 -machine q35 -device pcie-root-port,port=0x10,chassis=1,id=pci.1,bus=pcie.0,multifunction=on,addr=0x3 -device pcie-root-port,port=0x11,chassis=2,id=pci.2,bus=pcie.0,addr=0x3.0x1 -device pcie-root-port,port=0x12,chassis=3,id=pci.3,bus=pcie.0,addr=0x3.0x2 -device virtio-scsi-pci,bus=pci.2,addr=0x0,id=scsi0 -device scsi-hd,bus=scsi0.0,drive=hd0 -machine accel=kvm:tcg -cpu host -no-reboot -cpu max -machine q35 -device isa-debug-exit -m 2G -drive file=/home/fredrikbakken/.ops/images/dart.img,format=raw,if=none,id=hd0 -device virtio-net,bus=pci.3,addr=0x0,netdev=n0 -netdev user,id=n0 -display none -serial stdio
assigned: 10.0.2.15
dispatch_signals error: signal 11 resulting in core dump
unimplemented signal
ffffffff80014726        (kern_unlock + 0000000000000056/0000000000000070)
ffffffff80003296        (kernel_shutdown + 0000000000000066/0000000000000074)
ffffffff8000b56e        (halt + 00000000000000de/00000000000000e2)
ffffffff800513f7        (dispatch_signals + 0000000000000587/00000000000005ef)
ffffffff800633f5        (run_thread + 0000000000000015/000000000000001d)
ffffffff80014a7f        (runloop_internal + 000000000000030f/0000000000000492)
assertion l->w == 1 failed in /home/eyberg/go/src/github.com/nanovms/nanos/src/x86_64/lock.h: spin_unlock() on line 40; halt
ffffffff80014726        (kern_unlock + 0000000000000056/0000000000000070)
ffffffff80003296        (kernel_shutdown + 0000000000000066/0000000000000074)
ffffffff8000b56e        (halt + 00000000000000de/00000000000000e2)
ffffffff80014740        (kernel_sleep + 0000000000000000/0000000000000024)
ffffffff80003296        (kernel_shutdown + 0000000000000066/0000000000000074)
ffffffff8000b56e        (halt + 00000000000000de/00000000000000e2)
ffffffff800513f7        (dispatch_signals + 0000000000000587/00000000000005ef)
ffffffff800633f5        (run_thread + 0000000000000015/000000000000001d)
ffffffff80014a7f        (runloop_internal + 000000000000030f/0000000000000492)
assertion l->w == 1 failed in /home/eyberg/go/src/github.com/nanovms/nanos/src/x86_64/lock.h: spin_unlock() on line 40; halt
ffffffff80014726        (kern_unlock + 0000000000000056/0000000000000070)
ffffffff80003296        (kernel_shutdown + 0000000000000066/0000000000000074)
ffffffff8000b56e        (halt + 00000000000000de/00000000000000e2)
ffffffff80014740        (kernel_sleep + 0000000000000000/0000000000000024)
ffffffff80003296        (kernel_shutdown + 0000000000000066/0000000000000074)
ffffffff8000b56e        (halt + 00000000000000de/00000000000000e2)
ffffffff80014740        (kernel_sleep + 0000000000000000/0000000000000024)
ffffffff80003296        (kernel_shutdown + 0000000000000066/0000000000000074)
ffffffff8000b56e        (halt + 00000000000000de/00000000000000e2)
ffffffff800513f7        (dispatch_signals + 0000000000000587/00000000000005ef)
ffffffff800633f5        (run_thread + 0000000000000015/000000000000001d)
ffffffff80014a7f        (runloop_internal + 000000000000030f/0000000000000492)
...
frame trace:

frame ffff8000014a0000 already full
cpu 0000000000000000, state user, vector 000000000000000e
 interrupt: 000000000000000e (Page fault)
     frame: ffff8000014a0000
error code: 0000000000000002
   address: ffff8000014a7ff8

   rax: 2248959df8b61a5c
   rbx: ffff8000014a8030
   rcx: 00000000000003d5
   rdx: ffff8000014a7fc0
   rsi: 0000000000000008
   rdi: ffff8000014a8030
   rbp: ffff8000014a8000
   rsp: ffff8000014a7fc0
    r8: 000000000000004d
    r9: 00000000000003d5
   r10: 0000000000001f90
   r11: 00000000000bbf20
   r12: 0000000000000010
   r13: ffffffff800adbbc
   r14: ffffffff800adbbc
   r15: ffff800001480150
   rip: ffffffff8008a438        (validate_virtual + 0000000000000018/0000000000000057)
rflags: 0000000000010086
    ss: 0000000000000000
    cs: 0000000000000008
    ds: 0000000000000000
    es: 0000000000000000
fsbase: 0000000000000000
gsbase: 0000000000000000
...

Are there any obvious mistakes I have made while setting up this local package?

needs investigation

opened by FredrikBakken 22

.staging turds everywhere

I noticed that whenever i run the ops command, a .staging directory is created in the pwd, which leaves .staging directories all over the place on my filesystem. Its surprising that running a command like ops list creates directories and in the pwd.

Is this on purpose? I can imagine linux purist getting pissy about the uncleanliness of this.

opened by cbarraford 21
No default IP assigned in hyper-v

When we run with qemu (e.g. ops run myapp), the first line shows up the default IP address added by nanos:

deploying to hyper-v, however, does not assign a default IP address:

there are two 0.0.0.0 and a 127.0.0.1 in hyper-v instance when all interfaces are queried programmatically; compared to qemu instance, which has 10.0.2.15 and 127.0.0.1 out of the box.

ps: btw, going by this docs section, manually adding "RunConfig": { "IPAddr": "10.0.2.30"} to config.json has no effect on qemu or hyper-v instances..

opened by am11 19
Enabled ENA for ami

Hello folks,

Is anyone know, how to Enabled ENA for ami which is created by ops (cmd tool for nanovms). for instance ena is enabled but for ami not enabled.

cmd:-

ops instance create server -c config.json -t aws -z ap-south-1 -i server-image --port 8080 --flavor t3.medium

Error:-

Could not create instance %!(EXTRA *awserr.requestError=InvalidParameterCombination: Enhanced networking with the Elastic Network Adapter (ENA) is required for the 't3.medium' instance type. Ensure that you are using an AMI that is enabled for ENA. status code: 400, request id: ffdb9e82-3f23-49e5-91bf-b5914c98d028)InvalidParameterCombination: Enhanced networking with the Elastic Network Adapter (ENA) is required for the 't3.medium' instance type. Ensure that you are using an AMI that is enabled for ENA. status code: 400, request id: ffdb9e82-3f23-49e5-91bf-b5914c98d028
question

opened by kalyanGK1 18
Security account for new instance on GCP

Hello. The gcloud cli will apparently attach the default security account to an instance created using that method. However, it is noted that a security account is not attached when creating an instance using some other means (not really specified). I have found that when using OPS to create an instance from an image there is no security account attached. Also, the image is created in a started state. I could be missing something. However, to work around this issue I have added calls to stop the image, attach the account and desired scope(s), then restart. This seems to work. As I have said, I could be wrong about what is happening, but if not, would it be possible to create an instance in a stopped state to avoid having to stop it before adding the security account? I really am enjoying OPS and how well it is able to create images and instances and have found calls to the gcloud cli to integrate well with ops to add in actions more appropriately handled there.
question

opened by imarsman 14

Running Python Streamlit App On Ops Locally

Hi,

I'm trying to convert a streamlit app (initially hosted on Heroku) to running on ops. My machine is running Ubuntu 20.04. In the app folder I first run this setup.sh script:

python3 -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt # only streamlit and requests

mkdir -p .streamlit/
echo "\
[server]\n\
headless = true\n\
port = $PORT\n\
enableCORS = false\n\
\n\
" > .streamlit/config.toml

Then my config.json looks like:

{
"MapDirs": {
"./env/*": "/.local",
"./.streamlit": "/.streamlit",
"/usr/lib64/*": "/usr/lib/x86_64-linux-gnu"
},
"Dirs": ["usr", "lib"],
"Args": ["streamlit", "run", "app.py"],
"Files": ["app.py"]
}

This is the traceback:

$ ops pkg load python_3.8.6 -c config.json -p 8501
 100% |████████████████████████████████████████|  [0s:0s]
panic: lstat : no such file or directory

goroutine 1 [running]:
github.com/nanovms/ops/cmd.loadCommandHandler(0xc000612840, 0xc000142870, 0x1, 0x5)
	/Users/eyberg/go/src/github.com/nanovms/ops/cmd/cmd_pkg.go:328 +0x597
github.com/spf13/cobra.(*Command).execute(0xc000612840, 0xc000142820, 0x5, 0x5, 0xc000612840, 0xc000142820)
	/Users/eyberg/go/pkg/mod/github.com/spf13/[email protected]/command.go:846 +0x2c2
github.com/spf13/cobra.(*Command).ExecuteC(0xc0000a3600, 0x0, 0x1f94fe0, 0xc000114058)
	/Users/eyberg/go/pkg/mod/github.com/spf13/[email protected]/command.go:950 +0x375
github.com/spf13/cobra.(*Command).Execute(...)
	/Users/eyberg/go/pkg/mod/github.com/spf13/[email protected]/command.go:887
main.main()
	/Users/eyberg/go/src/github.com/nanovms/ops/ops.go:8 +0x2a

opened by gfleetwood 13

RangeError: Index out of range

Getting this error when run ops run using the vscode extension.

What could be the possible issue?

booting /home/shahidshaikh/.ops/images/node ... [1;33mYou specified hardware acceleration, but it is not supported Are you running inside a vm? If so disable accel with --accel=false [0m [1;33mAnyway, we will try to enable hardware acceleration [0mstderr: Could not access KVM kernel module: No such file or directory qemu-system-x86_64: failed to initialize KVM: No such file or directory stderr: qemu-system-x86_64: Back to tcg accelerator en1: assigned 10.0.2.15 en1: assigned FE80::18E9:80FF:FE34:7D33 buffer.js:607 slice: (buf, start, end) => buf.utf8Slice(start, end), ^

RangeError: Index out of range at Object.slice (buffer.js:607:37) at Buffer.toString (buffer.js:804:14) at Object.readFileSync (fs.js:408:41) at Object.Module._extensions..js (internal/modules/cjs/loader.js:1195:22) at Module.load (internal/modules/cjs/loader.js:1040:32) at Function.Module._load (internal/modules/cjs/loader.js:929:14) at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:71:12) at internal/main/run_main_module.js:17:47 { code: 'ERR_OUT_OF_RANGE' } exit status 3

opened by shaikh-shahid 13

Print volume size in volume list table

Description

Prints the volume size alongside other values in the list volumes table. It first parses the size value into a human readable format using the helper functions in lepton/helpers.go. Example

./ops volume list
+----------+--------------------------------------+--------+------------------------------------------------+
|   NAME   |                 UUID                 |  SIZE  |                      PATH                      |
+----------+--------------------------------------+--------+------------------------------------------------+
| test_vol | 9aa1a2a1-4d6d-a340-03d2-a77b05484c16 | 1.0 kB | /home/ahmedaabouzied/.ops/volumes/test_vol.raw |
+----------+--------------------------------------+--------+------------------------------------------------+

If there is an error parsing the size value of a certain volume, it prints an error instead indicating the name, ID of the volume with the invalid value as follows

./ops volume list
2020/09/23 04:45:57 invalid size value for volume test_vol with UUID 1352848a-547a-c67c-fce9-5f1e8e52bc8e: strconv.ParseFloat: parsing "": invalid syntax

Fixes #608

UPDATE

Fixes #638 as well

opened by ahmedaabouzied 13

Auto install haxm.
Things to do: https://github.com/nanovms/ops/issues/141

[x] ~enumerate osx version to determine what .dmg should be loaded~

[x] prompt but don't demand the user install hax

[x] need perms request in installer

[ ] possibly create new signed dmgs

[x] implement kexst check for osx (to see if there is hax enabled)

[ ] re-eval perms issues to make this easy for end-users - i'm kinda thinking that if the installer script can be smart enough to detect vt-x and friends it should just go ahead and setup necessary permissions so that the user can run this stuff w/out sudo everytime - there's an implication here that most real deployments are going to be pushed through public clouds regardless so it's a bit of a mute issue for local

[x] use acceleration flag appropriate to host OS.
opened by ExternalReality 13
Start work on removing .staging directory
This PR created to change the way ".staging" directory was used. In this PR:

temp directory is determined based on OS you are running

directory in "temp" one is named according to cons OpsDir

file that contains information about contents in that directory is const TMPContentsFile

another temp directories are created using Go ioutil.TempDir with prefix const TMPStagingDirectoryPrefix

Uniqueness is done using the following methods:

If user uses run command then full path to it's binary is used (ex. /Users/alexvwan/dev/src/test/server) with it's association to new unique temp directory

If user uses load command then full path to current directory + gathered from manifest manifest.Program
opened by anikitenko 13
Python 3.10 package missing libz
I'm excited to start using the eyberg/python:3.10.6 image, but I noticed that I cannot import base64; I believe this is because libz.so.1 is missing from the package image.

(eyberg/python:3.9.7 has it:)

ops pkg contents eyberg/python:3.9.7 | grep libz File :/sysroot/lib/x86_64-linux-gnu/libz.so.1

Personally I'd also like to see librt.so.1 as well (a dependency I use needs it, but doesn't use it AFAICT); none of the existing python packages have that but I wish they did!
opened by paulreimer 12
modify fw rules to auto-delete w/out help from config

right now at least on gcp and probably elsewhere a config is mandatory to delete associated fw rules https://github.com/nanovms/ops/blob/master/gcp/gcp_instance.go#L287-L320

since we auto-create these by default and are tagging them as made by ops we should be able to scan for these resources and auto-delete them as well w/out needing a config
networking gcp

opened by eyberg 1

sometimes getting proxmox upload errors

Post "https://172.16.41.133:8006/api2/json/nodes/pve/storage/local/upload": write tcp 172.16.41.1:49449->172.16.41.133:8006: use of closed network connection

proxmox

opened by eyberg 0

proxmox checks generating spurious fails
run into what appears some timing issues periodically such as:

can not add virtio disk from local storage, check token permissions, environment variables correctness
opened by eyberg 0
don't auto-download latest arm build if already present

https://github.com/nanovms/ops/pull/1380 adds capability to download arm release on x86 for cross-arch deploys but right now the version check stuff needs to be refactored to take into account multiple architectures

opened by eyberg 0
investigate avx on mac m1s

we support it on other x86 machines (w/accel)

https://github.com/nanovms/ops/issues/1357

https://ahelpme.com/software/qemu/qemu-full-virtualization-cpu-emulations-enable-disable-cpu-flags-instruction-sets-of-qemu-6-2-0/

https://gitlab.com/qemu-project/qemu/-/issues/164

sample program that uses cpuid to check for avx:

https://gist.github.com/hi2p-perim/7855506

I think it's not implemented in TCG cause you can run it with hardware acceleration but it doesn't show up in TCG

opened by eyberg 1
mov all flag parsing for TargetConfig into a parsing function when instantiating a new image/instance

it's rather convoluted right now because it takes a string flag - parses it into the proper type and then immediately turns around passes it back as a different type of string (in many cases) to proxmox api
refactoring proxmox

opened by eyberg 0