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.

Parameters:

• 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

parse(zvsh_args)

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.

DEFAULT_NODE = 1

classmethod default_manifest(basedir, program)

dumps()

Get the text representation of the manifest.

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

Parameters:

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

dumps()

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.

add_agruments()

parse(zvsh_args)

class zvshlib.zvsh.ZvConfig

class zvshlib.zvsh.ZvRunner(command_line, stdout, stderr, tempdir, getrc=False)

print_error(rc)

report_reader()

run()

spawn(daemon, func, **kwargs)

stderr_reader()

stdin_reader()

stdout_write()

class zvshlib.zvsh.ZvShell(config, savedir=None)

add_arguments(args)

add_debug(zvm_debug)

add_debug_script()

add_image_args(zvm_image)

add_self()

add_untrusted_args(program, cmdline)

cleanup()

create_manifest()

create_manifest_channel(file_name)

create_nvram(verbosity)

zvshlib.zvsh._check_runtime_files(runtime_files)

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.

Parameters:

• 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')])

zvshlib.zvsh._nvram_escape(value)

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')
'foo\\x2c\\x20bar'
>>> _nvram_escape('new\nline')
'new\\x0aline'

zvshlib.zvsh._process_images(zvm_images)

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.

Example:

>>> 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)

Parameters:

• 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)

Parameters:

• manifest_cfg –

  dict containing the following keys:

  • Node
  • Version
  • Timeout
  • Memory

• limits_cfg –

  dict containing the following keys:

  • reads
  • rbytes
  • writes
  • wbytes

zvshlib.zvsh.is_binary_string(byte_string)

zvshlib.zvsh.parse_return_code(report)

zvshlib.zvsh.run_zerovm(zvconfig, zvargs)

Parameters:

• zvconfig – ZvConfig instance.
• zvargs – ZvArgs instance.

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.