ZeroVM CLI Core Functions

class zvshlib.zvsh.Channel(uri, alias, access_type, etag=0, gets=4294967296, get_size=4294967296, puts=4294967296, put_size=4294967296)

Definition of a channel within a manifest. Defines a mapping from the host to the ZeroVM filesystem, access type, and read/write limits.

  • uri – Path to a local file, pipe, character device, tcp socket or host ID.
  • alias – Path where this channel will be mounted in ZeroVM.
  • access_type

    Choose from the following:

    • 0: sequential read/ sequential write
    • 1: random read/ sequential write
    • 2: sequential read / random write
    • 3: random read / random write
  • etag

    etag switch; can be in the range 0..1

    Default: 0

  • gets

    Limit for number of reads from this channel.

    Default: 4294967296

  • get_size

    Limit on total amount of data to read from this channel, in bytes.

    Default: 4294967296

  • puts

    Limit for number of writes to this channel.

    Default: 4294967296

  • put_size

    Limit on total amount of data to be written to this channel, in bytes.

    Default: 4294967296

class zvshlib.zvsh.DebugArgs
class zvshlib.zvsh.Manifest(version, timeout, memory, program, node=1, etag=0, channels=None)

Object representation of a ZeroVM manifest. Includes utilities and sane defaults for generating manifest files.

classmethod default_manifest(basedir, program)

Get the text representation of the manifest.

class zvshlib.zvsh.NVRAM(program_args, processed_images, env=None, debug_verbosity=None)
  • program_args

    A list of the command args to be run inside ZeroVM. In the case of a Python application, this would be something like:

    [‘python’, ‘-c’, ‘print “hello, world”’]
  • processed_images – A list 3-tuples containing (image path, mount point, access). See _process_images() for more details.
  • env – Optional. dict of environment settings from zvsh.cfg.
  • debug_verbosity (int) – Optional. Debug verbosity level, in the range 0..4.

Generate the text for an nvram file.

class zvshlib.zvsh.ZvArgs
Attr parser:argparse.ArgumentParser instance, used to define the command line arguments.
Attr args:argparse.Namespace representing the command line arguments.
class zvshlib.zvsh.ZvConfig
class zvshlib.zvsh.ZvRunner(command_line, stdout, stderr, tempdir, getrc=False)
spawn(daemon, func, **kwargs)
class zvshlib.zvsh.ZvShell(config, savedir=None)
add_untrusted_args(program, cmdline)

Given a dict of runtime files (see the output _get_runtime_file_paths()), check if any exist. If any exist, raise a RuntimeError.

zvshlib.zvsh._extract_nexe(program_path, processed_images, command)

Given a command, search through the listed tar images (processed_images) and extract the nexe matching command to the target program_path on the host file system.

  • program_path – Location (including filename) which specifies the destination of the extracted nexe.
  • processed_images – Output of _process_images().
  • command – The name of a nexe, such as python or myapp.nexe.
zvshlib.zvsh._get_runtime_file_paths(working_dir, node)

Generate the runtime files paths for boot, manifest, nvram, stdout, and stderr files, and return them as a OrderedDict with the following structure:

>>> _get_runtime_file_paths('/home/user1', 1)
OrderedDict([('boot', '/home/user1/boot.1'), ('manifest', '/home/user1/manifest.1'), ('nvram', '/home/user1/nvram.1'), ('stdout', '/home/user1/stdout.1'), ('stderr', '/home/user1/stderr.1')])

Note that that paths are created by simply joining working_dir, so relatve file paths can be used as well:

>>> _get_runtime_file_paths('foo/', 1)
OrderedDict([('boot', 'foo/boot.1'), ('manifest', 'foo/manifest.1'), ('nvram', 'foo/nvram.1'), ('stdout', 'foo/stdout.1'), ('stderr', 'foo/stderr.1')])

Escape value for inclusion as a value in a nvram file.

The ini-file parser in ZRT is very simple. One quirk is that it handles ‘,’ the same as ‘n’, which means that a value like

greeting = Hello, World

will be cut-off after “Hello”.

Values also need protection in other ways:

  • When “args” are loaded, the value is split on ‘ ‘ and each argument found is then unescaped. This means that each arg need to have ‘ ‘ escaped.
  • When a “value” is loaded in [env], it is unescaped. It must therefore also be escaped.

This function escapes ‘\’, ‘”’, ‘,’, ‘ ‘, and ‘n’. These are the characters that conf_parser::unescape_string_copy_to_dest is documented to handle and they are sufficient to handle the above use cases.

>>> _nvram_escape('foo, bar')
>>> _nvram_escape('new\nline')

Process a list of the –zvm-image arguments and split them into the path,mount_point,access_type components. This returns a generator of 3-tuples.

mount_point and access_type are optional and will default to / and ro, respectively.


>>> list(_process_images(['/home/user1/foo.tar',
...                       '/home/user1/bar.tar,/var/lib',
...                       '/home/user1/baz.tar,/usr/lib,rw']))
[('/home/user1/foo.tar', '/', 'ro'), ('/home/user1/bar.tar', '/var/lib', 'ro'), ('/home/user1/baz.tar', '/usr/lib', 'rw')]
zvshlib.zvsh._run_zerovm(working_dir, manifest_path, stdout_path, stderr_path, zvm_trace, zvm_getrc)
  • working_dir – Working directory which contains files needed to run ZeroVM (manifest, nvram, etc.).
  • manifest_path – Path to the ZeroVM manifest, which should be in working_dir.
  • stdout_path – Path to the file into which stdout is written. This file should be in working_dir.
  • stderr_path – Path to the file into which stderr is written. This file should be in working_dir.
  • zvm_trace (bool) – If True, enable ZeroVM trace output into ./zvsh.trace.log.
  • zvm_getrc (bool) – If True, return the ZeroVM exit code instead of the application exit code.
zvshlib.zvsh.create_manifest(working_dir, program_path, manifest_cfg, tar_files, limits_cfg)
  • manifest_cfg

    dict containing the following keys:

    • Node
    • Version
    • Timeout
    • Memory
  • limits_cfg

    dict containing the following keys:

    • reads
    • rbytes
    • writes
    • wbytes
zvshlib.zvsh.run_zerovm(zvconfig, zvargs)
zvshlib.zvsh.spawn(argv, master_read=<function _read at 0x1f7c050>, stdin_read=<function _read at 0x1f7c050>)

Create a spawned process. Based on pty.spawn code.

Previous topic

Welcome to zerovm-cli’s documentation!

This Page