Extracting output files

After an application runs on OSv and produces an output file, how does one extract this file from the OSv image? Since Linux does not (out of the box) have ZFS support, one cannot simply mount the image on the host. So the simplest solution is to have OSv send the file over the network - either have it push the file to some server (using e.g., HTTP, NFS, etc.), or run inside OSv some server which allows the file to be pulled (e.g., using HTTP).

The goal of this document is to document some convenient methods of extracting files from a running OSv

The HTTP server

One of the example applications included in the OSv source repository is a simple HTTP server. It is usually used to add a "REST API" to OSv (for remotely monitoring or administrating a guest running OSv), but also provides a convenient method for retrieving a file from the image.

NOTE: This discussion does not include any sort of security. If your running image is accessibly from the Internet, anybody could retrieve your file just like you.

As an example, let's consider an image built with

scripts/build image=memcached

Let's say we want to extract the file /etc/hosts from this image (of course, this is just a silly example).

We can build the image with both memcached and the HTTP server:

scripts/build image=memcached,httpserver

If we now run it, it will run both the memcached server, and the additional httpserver (in separate threads). To run this image locally with scripts/run.py, because we want to allow network connection into the guest, we need to enable either bridged networking (run.py's -n option), or port forwarding. Let's try the latter:

$ scripts/run.py --api
OSv v0.20-8-g2e68dac
eth0: 192.168.122.15
Memcached for OSV, based on Memcached 1.4.21

The "--api" option forwards connections to localhost:8000 on the host to port 80 of the guest. So we can connect to the guest an fetch its file with a command like curl:

$ curl 'http://localhost:8000/file/etc/hosts?op=GET'
127.0.0.1 localhost osv.local

This is indeed the content of the /etc/hosts file 😄

Note how the URL has localhost:8000 (which, as explained above, is forwarded to port 80 on the guest), then /file (a file operation), then the desired file name /etc/hosts and finally the operation ?op=GET (get the file).

In the example above, we ran both the desired application and httpserver at the same time. In some situations, it is desireable to run them separately - i.e., first run only the application, which will generate some output and exit, and then run OSv again this time with only the http server. We can do this as follows:

scripts/build image=memcached,httpserver.none
scripts/run.py   # run only the application (memcached)
...
# after the previous run.py is done
scripts/run.py --api -e /libhttpserver.so

The httpserver.none in the image name adds the httpserver application to the image, without running anything by default. The -e /libhttpserver.so option to run.py tells it to run the http server program instead of the default application (memcached).