cosmk Python API reference

The CLI tool of the CLIP OS toolkit

Warning

This module has side-effects on the Python runtime!

Since parts of this module and its submodule require super-user rights to perform some vital operations (e.g. managing Linux containers or creating files with all kinds of user rights), this module must be imported from a privileged Python runtime (i.e. a runtime with EUID and EGID both equal to 0).

The side-effects on the Python runtime are explained by the fact that, on import, the real and effective UIDs and GIDs are changed to some unprivileged UID and GID (see Note below). This is made to be able to operate most of the time without explicit super-user privileges since most of the logic of this Python package do not require super-user privileges (e.g. for managing parts of the CLIP OS sources tree or parsing configuration files).

But as the saved-set UID and GID are kept to 0, it is still possible for the Python runtime to retrieve privileged real and effective UIDs and GIDs. This super-user privileges retrieval (also inaccurately referenced as privilege elevation) is done with the context manager cosmk.privileges.ElevatedPrivileges which temporarily flips the values of both real and effective UIDs and GIDs with the values of saved-set UID and GID (respectively) and vice versa. This enables us to build seamless privileged sections of code without having to invoke sudo or any other method or privileges elevation (that may require user intevention such as password entry).

Please note that this construction was never meant to be a security mechanism against unsafe code evaluation as it is still possible to retrieve elevated privileges with the same method as the ElevatedPrivileges context manager does. The only purpose of this was to avoid running the whole cosmk package and its module dependencies with a privileged Python runtime which might cause issues.

If imported from an unprivileged Python runtime, this module will fail at the first attempt of privileges elevation with the context manager cosmk.privileges.ElevatedPrivileges.

Note

Since the context manager cosmk.privileges.ElevatedPrivileges requires unprivileged UID and GID to change both real and effective UIDs and GIDs at initialization, this module uses the environment variables SUDO_UID and SUDO_GID. These variables are provided by the famous utility sudo and contain the unprivileged UID and GID. This is the reason why the cosmk utility recalls itself through sudo when launched without super-user privileges.

cosmk.__main__ module

The CLIP OS toolkit command line utility

cosmk.__main__.main(as_module=False)[source]

Main function of the cosmk command-line utility.

Parameters:as_module (bool) – True when called as a module (e.g. python -m cosmk)
Return type:None
cosmk.__main__.sudo_ourselves()[source]

Replace the current process by recalling the same command that originated the current process (using sys.argv) but by calling it through sudo. In case of success, this function does not return since it calls execve(2).

The command line that calls sudo ensures to keep the environment variables of the unprivileged user (as well as the contents of PATH which can be overwritten by Sudo for safety reasons).

Note

This requires Sudo 1.8.21 or above.

Raises:CosmkError – if sudo could not be found in PATH or if the call has failed
Return type:None

cosmk.commons module

Miscellanous utility functions and helpers that may be used globally in this package.

cosmk.commons.is_tty_attached()[source]

Checks if the current process is attached to a TTY (i.e. if both stdin, stdout and stderr are TTY).

Return type:bool
cosmk.commons.line(msg)[source]

Rewrap a message by stripping the unneeded indentation, removing leading and trailing whitespaces and joining all the lines into one unique text line.

>>> line('''
        A potentially long message that
        can overflow the 79 chars limit
        of PEP 8.
''')
"A potentially long message that can overflow the 79 chars limit of PEP 8."
Return type:str
cosmk.commons.linux_version()[source]

Returns the current Linux kernel version under the form of a 3-tuple of int (e.g. on a 4.16.12-1-ARCH Linux kernel, this function will return the tuple (4, 16, 12)).

Raises:CosmkEnvironmentError – in case the underlying system does not run a Linux kernel or if the kernel version string is unparseable
Return type:Tuple[int, int, int]
cosmk.commons.rewrap(msg)[source]

Rewrap a message by stripping the unneeded indentation and removing leading and trailing whitespaces.

Return type:str
cosmk.commons.run(cmd, terminal=False, stdout=None, stderr=None, stdouterr=None, timeout=None, check=True)[source]

Wrapper around the submodule.run function with capture of the output streams (stdout, stderr or both streams interlaced as one).

Parameters:
  • cmd (Union[List[str], str]) – the command line to run (either in the form of a sh-escaped command line string or a list of arguments as subprocess takes)
  • terminal (bool) – whether or not the terminal shall be forwarded to the command
  • stdout (Optional[Io[AnyStr]]) – file-object receiving the capture of the command stdout output stream
  • stderr (Optional[Io[AnyStr]]) – file-object receiving the capture of the command stderr output stream
  • stdouterr (Optional[Io[AnyStr]]) – file-object receiving the capture of the command output stream with both stdout and stderr interlaced (i.e. as it appears in an interactive shell without output redirection)
  • timeout (Optional[int]) – the time out value to apply to the command run
  • check (bool) – raise an exception if the command exits with a non-null return value
Raises:
Return type:

None

cosmk.completion module

Auto-completion helpers to be used with argcomplete and argparse methods within cosmk.__main__.

cosmk.completion.features_for_action(action)[source]

Returns the list of recipe feature names which provide the given action name.

Parameters:action (str) – the requested action name
Return type:List[str]
cosmk.completion.product_completer(prefix, parsed_args, **kwargs)[source]

Returns a list of all the products available in the current repo source tree.

Return type:Iterable[str]
cosmk.completion.recipe_completer(prefix, parsed_args, **kwargs)[source]

Returns a list of all the recipes available in the current repo source tree that would be appropriate regarding the current parsed arguments from the main() function of cosmk.

Return type:Iterable[str]

cosmk.container module

Module providing functions and classes to handle OCI Linux containers with runc.

class cosmk.container.Container(name, rootfs, hostname=None, readonly_root=False, shared_host_netns=False)[source]

Bases: object

Overly-simplified Linux OCI container abstraction with wrappers around the runc runtime for the command execution methods.

Parameters:
  • name (str) – the name of the container
  • rootfs (str) – the path to the rootfs squashfs image file
  • hostname (Optional[str]) – the hostname within the container (defaults to the container name if set to None)
  • readonly_root (bool) – whether or not the rootfs shall be read-only mounted
  • shared_host_netns (bool) – whether or not the container shall share the network namespace of the host in order to have networking access (to prevent having the hassle to configure IP routing and filtering on the host for this container)

Note

Eventhough this abstraction can be used independently outside of cosmk context, this class (and this module in a greater extent) is primarily intended to be used by the CLIP OS SDK abstraction to produce ephemeral containers (i.e. container sessions with their rootfs meant to be destroyed on closing, with still the possibility of being snapshotted into a reusable container squashfs image).

OCI_SPECS_VERSION = (1, 0, 0)
RUNTIME_WORKING_DIR_REPO_SUBPATH = 'run/containers'
mountpoints

This list does not include the root mountpoint.

Return type:List[ContainerMountpoint]
required_mountpoints

The usual required default system mountpoints (e.g. /proc, /dev, etc.) for the container to run properly.

Return type:List[ContainerMountpoint]
run(*args, **kwargs)[source]

Shortcut function to run a single command in this container (a session will be instanciated temporarily just for this command).

Return type:None
session()[source]

Creates a session from this container in order to be able to call multiple commands on the same container instance and/or snapshotting the container contents into a squashfs image reusable by the Container class for future usage.

This context manager is in charge of creating the runc bundle as a temporary directory (“temporary” meaning that its existence will be limited to the time span where the context manager is opened). This context manager has also the responsibility of mounting the container root filesystem (from its base squashfs image) in the suitable directory.

Return type:Iterator[ContainerSession]
unshared_namespaces
Return type:Set[str]
class cosmk.container.ContainerDeviceBinding(host_device, container_device=None)[source]

Bases: object

Device node binding for a container that can be output as a dict for the runc JSON spec.

Note

The OCI runtime automatically provides these devices nodes: /dev/null, /dev/zero, /dev/full, /dev/random, /dev/urandom, /dev/tty, /dev/console, /dev/ptmx. Therefore, there is no need to specify them. See: <https://github.com/opencontainers/runtime-spec/blob/master/config-linux.md#default-devices>_

as_dict()[source]

Return this container device binding as a dict ready to be JSON-ified for the runc config.json specification.

Return type:Any
cgroup_authorization_dict()[source]

Return the device cgroup authorization dict structure ready to be JSON-ified for the runc config.json specification.

Return type:Any
class cosmk.container.ContainerMountpoint(source, target, type=None, options=None)[source]

Bases: object

Mountpoint for a container (with the destination path within the container rootfs) that can be output as a dict for the runc JSON spec.

as_dict()[source]

Return this container mountpoint as a dict ready to be JSON-ified for the runc config.json specification.

Return type:Any
class cosmk.container.ContainerSession(container, bundle_dir, runc_container_name)[source]

Bases: object

Session of a container instance.

run(command, cwd='/', env=None, terminal=False, user=(0, 0), stdout=None, stderr=None)[source]

Run a command in this container session.

Parameters:
  • command (List[str]) – the command to run (command line splitted into a list in the manner of the argv argument of the traditional execve(2) syscall)
  • cwd (str) – the current working directory
  • env (Optional[Dict[str, str]]) – the environment variable set
  • terminal (bool) – hook the current TTY to the container if True
  • user (Tuple[int, int]) – UID and GID couple values to use for the process run in the container
  • stdout (Optional[Io[AnyStr]]) – facultative stream object able to receive for writing the standard output of the process run in the container
  • stderr (Optional[Io[AnyStr]]) – facultative stream object able to receive for writing the standard error output of the process run in the container
Return type:

None

snapshot(squashfs_filepath)[source]

Snapshot the rootfs of this container

Return type:None

cosmk.exceptions module

CLIP OS toolkit exceptions

exception cosmk.exceptions.ContainerSnapshotError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when a container sesssion snapshotting fails.

exception cosmk.exceptions.CosmkEnvironmentError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when the runtime environment does not meet the requirements to run properly (e.g. a system utility command is missing).

exception cosmk.exceptions.CosmkError[source]

Bases: Exception

Base exception for all the other cosmk related exceptions. This exception can also be raised when the error is unknown or unhandled by the tool.

exception cosmk.exceptions.InstrumentationSpecificationError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when the “instrumentation.toml” drop-in file is badly formatted or has unexpected content.

exception cosmk.exceptions.ProductPropertiesError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when a product has a bad “properties.toml” definition.

exception cosmk.exceptions.ProjectInRepoSourceTreeInUncleanState[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when a project within the CLIP OS repo source tree is not in a clean state (e.g. unstaged elements).

exception cosmk.exceptions.RecipeActionError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when a recipe has a bad “recipe.toml” definition.

exception cosmk.exceptions.RecipeConfigurationError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when a recipe has a bad “recipe.toml” definition.

exception cosmk.exceptions.RepoSourceTreeManifestParsingError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when a repo manifest file has an unexpected XML structure or cannot be parsed as valid XML.

exception cosmk.exceptions.SdkBootstrapError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when an error occurs while bootstrapping a SDK image.

exception cosmk.exceptions.SdkError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when an error occurs inside a SDK container.

exception cosmk.exceptions.SdkNotFoundError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when a target requires a SDK which cannot be found because it has not been bootstrap (i.e. built) yet.

exception cosmk.exceptions.SystemCommandError(command, reason=None, stdout=None, stderr=None, stdouterr=None)[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when a system command (such as mount(8) or losetup(8)) fails. Reason should be provided as arguments to the exception.

exception cosmk.exceptions.UnexpectedRepoSourceTreeStructure[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when the repo directory structure does not match what is expected or when the “.repo” directory cannot be found in the underlying directory tree of the current working directory.

exception cosmk.exceptions.VirtualizedEnvironmentError[source]

Bases: cosmk.exceptions.CosmkError

Exception raised when an operation on a virtualized environment (e.g. a libvirt “domain”, a network configuration made by libvirt, etc.) cannot be pursued or has failed.

cosmk.features module

This module manages all the recipe features.

These recipe features act like traits for recipe.Recipe’s.

class cosmk.features.RecipeBundleFeature(recipe)[source]

Bases: cosmk.features.RecipeFeature

Recipe feature for bundling (e.g. making a tar archive or a squashfs image from any previous result of another recipe) whole or parts of the final recipe target.

FEATURED_ATTRIBUTES = {'bundle'}
NAME = 'bundle'
SCHEMA = Schema({'bundle': {'sdk': Regex('^[^\\s/]+/[^\\s/]+$'), Optional('env'): {Regex('^[a-zA-Z\\_][a-zA-Z0-9\\_]*$'): <class 'str'>}, 'steps': And([<class 'str'>], <built-in function len>)}, <class 'str'>: <class 'object'>})
bundle()[source]
Return type:None
class cosmk.features.RecipeConfigureFeature(recipe)[source]

Bases: cosmk.features.RecipeFeature

Recipe feature for configuring root trees built during a recipe root feature

FEATURED_ATTRIBUTES = {'configure'}
NAME = 'configure'
SCHEMA = Schema({'configure': {'sdk': Regex('^[^\\s/]+/[^\\s/]+$'), Optional('env'): {Regex('^[a-zA-Z\\_][a-zA-Z0-9\\_]*$'): <class 'str'>}, 'root': Regex('^[^\\s/]+/[^\\s/]+$'), 'steps': And([<class 'str'>], <built-in function len>)}, <class 'str'>: <class 'object'>})
configure()[source]

TODO

Return type:None
class cosmk.features.RecipeFeature(recipe)[source]

Bases: object

Recipe feature meta-class

Parameters:

recipe (Recipe) – the recipe on which this feature applies

Variables:
  • NAME – the name of the feature that can be specified in the features list in the recipe configuration files to specify that a recipe implements this current feature
  • FEATURED_ATTRIBUTES – the set of all the featured attributes provided to the Recipe object by this recipe feature
  • SCHEMA – the dict schema for the recipe configuration part relative to the current feature

Note

This is a metaclass and therefore must not be used or initialized directly. Use a subclass of this metaclass.

FEATURED_ATTRIBUTES = set()
NAME = '<meta-feature>'
SCHEMA = Schema({})
replace_placeholders(s, sdk_context=False)[source]

Replace the placeholders of a given string s and return a copy of this string.

Return type:str
class cosmk.features.RecipeRootFeature(recipe)[source]

Bases: cosmk.features.RecipeFeature

Recipe feature for building rootfs from sources and binary packages

FEATURED_ATTRIBUTES = {'build', 'image'}
NAME = 'root'
SCHEMA = Schema({'root': {'sdk': Regex('^[^\\s/]+/[^\\s/]+$'), Optional('env'): {Regex('^[a-zA-Z\\_][a-zA-Z0-9\\_]*$'): <class 'str'>}, 'build_steps': [<class 'str'>], 'image_steps': And([<class 'str'>], <built-in function len>)}, <class 'str'>: <class 'object'>})
build(clear_cache=False, clear_previous_build=True)[source]

Build a root tree for this recipe from sources and binary packages cache.

Parameters:
  • clear_cache (bool) – whether or not the cache has to clear before processing root build
  • clear_previous_build (bool) – whether or not the previous root build result has to be cleared
Return type:

None

image()[source]

Build a root tree for this recipe only from binary packages cache and without any build-time dependency.

Return type:None
class cosmk.features.RecipeSdkFeature(recipe)[source]

Bases: cosmk.features.RecipeFeature

Recipe feature for creating and proposing SDK objects to other features.

FEATURED_ATTRIBUTES = {'bootstrap', 'run', 'sdk'}
NAME = 'sdk'
SCHEMA = Schema({'runtime': {'additional_capabilities': [<class 'str'>], 'additional_device_bindings': [<class 'str'>], 'cwd': And(<class 'str'>, <built-in function len>), 'prelude_commands': [<class 'str'>], 'postlude_commands': [<class 'str'>], Optional('env'): {Regex('^[a-zA-Z\\_][a-zA-Z0-9\\_]*$'): <class 'str'>}, 'writable_assets_dirs_at_build': [And(<class 'str'>, <built-in function len>)]}, 'bootstrap': {'rootfs_archive': <class 'str'>, Optional('env'): {Regex('^[a-zA-Z\\_][a-zA-Z0-9\\_]*$'): <class 'str'>}, 'steps': [<class 'str'>]}, 'run': {Optional('env'): {Regex('^[a-zA-Z\\_][a-zA-Z0-9\\_]*$'): <class 'str'>}, 'steps': And([<class 'str'>], <built-in function len>)}, <class 'str'>: <class 'object'>})
bootstrap()[source]
Return type:None
run()[source]
Return type:None
sdk
Return type:Sdk
class cosmk.features.RecipeSignatureFeature(recipe)[source]

Bases: cosmk.features.RecipeFeature

Recipe feature for XXX

NAME = 'sign'
class cosmk.features.RecipeVirtualizedEnvironmentFeature(recipe)[source]

Bases: cosmk.features.RecipeFeature

Recipe feature for creating, running and cleaning virtualized environment created from other recipe feature results.

FEATURED_ATTRIBUTES = {'create', 'spawn', 'destroy'}
NAME = 'virt'
SCHEMA = Schema({'virt': {'xml_domain_template': And(<class 'str'>, <built-in function len>), 'xml_network_template': And(<class 'str'>, <built-in function len>), 'ovmf_code': And(<class 'str'>, <built-in function len>), 'ovmf_vars_template': And(<class 'str'>, <built-in function len>), 'qcow2_main_disk_image': And(<class 'str'>, <built-in function len>)}, <class 'str'>: <class 'object'>})
create(destroy_preexisting=False, spawn_virt_manager_console=False)[source]
Return type:None
destroy()[source]
Return type:None
spawn(destroy_preexisting=False, spawn_virt_manager_console=True)[source]
Return type:None
virtualized_environment
Return type:VirtualizedEnvironment

cosmk.fs module

Module providing filesystem-related utility functions and classes.

The host system must provide some command line utilities such as losetup(8) or mksquashfs.

class cosmk.fs.LoopDevice(backfile, device=None, readonly=False)[source]

Bases: object

Simple loop device object abstraction that can be used as a context manager.

class cosmk.fs.OverlayfsMount(mergeddir, lowerdir, upperdir=None, workdir=None, options=None)[source]

Bases: object

Simple overlayfs mountpoint object abstraction that can be used as a context manager to mount an overlayfs onto a given mountpoint.

class cosmk.fs.SquashfsMount(squashfile, mountpoint)[source]

Bases: object

Simple squashfs mountpoint object abstraction that can be used as a context manager to mount squashfs files onto a given mountpoint.

class cosmk.fs.TmpfsMount(mountpoint, **options)[source]

Bases: object

Simple tmpfs mountpoint object abstraction that can be used as a context manager to mount a tmpfs mountpoint.

cosmk.fs.close_loop(device)[source]

Close a loopback device node.

Return type:None
cosmk.fs.loop_devices()[source]

Get the loop devices currently set up on the system.

Return type:List[LoopDevice]
cosmk.fs.mksquashfs(squashfs_file, source_dir, compressor='gzip', store_xattrs=True, detect_sparse_files=True, compress_inode_table=False, compress_data_blocks=False, compress_fragment_blocks=False, compress_extended_attributes=False, find_duplicates=False)[source]

Wrapper around the command mksquashfs

Parameters:
  • squashfs_file (str) – the path to the squashfs file to produce
  • source_dir (str) – the directory to compress into a squashfs
  • compressor (str) – the compression method to use
  • store_xattrs (bool) – whether to save extended attributes or not
  • detect_sparse_files (bool) – activate sparse file detection (recommended)
  • compress_inode_table (bool) – compress the inode table
  • compress_data_blocks (bool) – compress data blocks
  • compress_fragment_blocks (bool) – compress fragment blocks
  • compress_extended_attributes (bool) – compress extended attributes
  • find_duplicates (bool) – perform duplicate checking
Return type:

None

cosmk.fs.open_loop(backfile, device=None, readonly=False)[source]

Open a loopback device given a back-file and eventually the device node to use.

Return type:None

cosmk.healthcheck module

CLIP OS toolkit healthcheck functions and stuff

cosmk.healthcheck.check_system()[source]
Return type:None
cosmk.healthcheck.healthcheck()[source]

Verify that the current system has everything to make work properly cosmk. This verifies that the Linux kernel version and the available features are , the availability of the required system utilities, the filesystem options of the repo root underlying mountpoint, the available free space on this mountpoint, etc.

TODO: extend this list :)

Return type:None

cosmk.instrumentation module

Module handling recipe instrumentation logic.

class cosmk.instrumentation.InstrumentationLevel[source]

Bases: enum.Enum

Instrumentation level enumeration for the recipes

DEBUG = 2
DEVELOPMENT = 1
PRODUCTION = 0
cosmk.instrumentation.instrumented_recipes()[source]

Probes for existence of an “instrumentation.toml” drop-in file at the root of the repo source tree, parses this file and return a dict of all the recipe identifiers (as keys) requested to be instrumented with their instrumentation level as value.

Raises:InstrumentationSpecificationError – in case of an incoherence in the instrumentation.toml file
Return type:Dict[str, InstrumentationLevel]

cosmk.log module

Logging utility functions and helpers.

cosmk.log.critical(msg)[source]

Log a message as logging.CRITICAL level.

Parameters:msg (str) – the message to log
Return type:None
cosmk.log.debug(msg)[source]

Log a message as logging.DEBUG level.

Parameters:msg (str) – the message to log
Return type:None
cosmk.log.error(msg)[source]

Log a message as logging.ERROR level.

Parameters:msg (str) – the message to log
Return type:None
cosmk.log.info(msg)[source]

Log a message as logging.INFO level.

Parameters:msg (str) – the message to log
Return type:None
cosmk.log.warn(msg)[source]

Log a message as logging.WARNING level.

Parameters:msg (str) – the message to log
Return type:None

cosmk.mount module

Module providing mount point management objects.

The host system must provide a mount(8) and umount(8) command line utilities available through PATH.

class cosmk.mount.Mountpoint(source, target, type=None, options=None)[source]

Bases: object

Mountpoint object that can be used as a context manager for contextualized mounts.

cosmk.mount.mount(source, target, type=None, options=None)[source]

Mount function with usage reflecting the traditional UNIX mount(8) command line utility.

Raises:SystemCommandError – in case of failure of the mount call (reason inside the exception)
Return type:None
cosmk.mount.mounts()[source]

Return the list of the mount points in the current mnt namespace. In other words, it basically wraps the contents of the pseudo-file /proc/mounts into an easily manipulable Python object.

Return type:List[Mountpoint]
cosmk.mount.umount(target)[source]

Unmount function with usage reflecting the traditional UNIX umount(8) command line utility.

Parameters:target (str) – the mountpoint to unmount
Raises:SystemCommandError – in case of failure of the umount call (reason inside the exception)
Return type:None

cosmk.privileges module

class cosmk.privileges.ElevatedPrivileges[source]

Bases: object

Context manager class to be used to elevate privileges locally within Python code of this cosmk module.

static possible()[source]

Evaluates if the privileges elevation is possible by doing a RES{U,G}ID flip over.

Return type:bool
cosmk.privileges.init_lower_privileges(uid, gid)[source]

Function to lower privileges (i.e. change real and effective UIDs and GIDs to UID/GID values given as arguments) intended to be called at cosmk module importation.

Return type:None

cosmk.product module

Module for products manageable with cosmk

class cosmk.product.Product(name)[source]

Bases: object

Class describing a CLIP OS (or one of its derivative) product.

Parameters:name (str) – the name of the product (e.g. clipos)
SCHEMA = Schema({'version': And(<class 'str'>, <built-in function len>, <function parse>), <class 'str'>: <class 'object'>})
tainted_version

Returns the version of this product as defined in its “properties.toml” file but “tainted” with a build flag instrumentation if an “instrumentation.toml” file is present at the root of the repo source tree.

Return type:str
validate_properties(prop_dict)[source]

Validate the data structure of the product properties file (“properties.toml”) and reorganize them into a “flattened” dict.

Parameters:prop_dict (Dict[str, Any]) – the properties dict object to validate against the schema (SCHEMA)
Raises:ProductPropertiesError – in case of bad data structure
Return type:Dict[str, str]
version

Returns the version of this product as defined in its “properties.toml” file.

Return type:str

cosmk.recipe module

The CLIP OS and derivatives recipe abstraction

class cosmk.recipe.Recipe(identifier)[source]

Bases: object

A CLIP OS toolkit recipe.

Parameters:identifier (str) – the identifier of the recipe (e.g. clipos/core)
cache_subpath

Returns the cache directory sub-path within the repo root.

Return type:str
meta_schema

The schema for which the recipe configuration file (recipe.toml) needs to comply for common part (i.e. the part of the configuration common to all the recipes)

Return type:Schema
out_subpath

Returns the output directory sub-path within the repo root.

Return type:str
validate_metaconfig(config)[source]

Validate the data structure of the recipe configuration file (“recipe.toml”) which do not concern any feature implementation (i.e. the “meta” part of the recipe configuration).

Parameters:config (Dict[str, Any]) – the configuration dict object to validate against the recipe meta schema
Raises:RecipeConfigurationError – in case of bad data structure
Return type:Dict[str, Any]

cosmk.sourcetree module

This module provide all the logic, functions and classes to manage the CLIP OS source tree. In a greater extent, this CLIP OS source tree is also managed by the repo tool but this module provide enhanced functionalities to those provided only by repo.

class cosmk.sourcetree.CommentedTreeBuilder(*args, **kwargs)[source]

Bases: xml.etree.ElementTree.TreeBuilder

An xml.etree.ElementTree.TreeBuilder subclass that retains XML comments.

comment(data)[source]
Return type:None
cosmk.sourcetree.fix_output_nodes_ownerships()[source]
Return type:None
cosmk.sourcetree.is_repo_root(path)[source]

Returns True if the given path contains a “.repo” directory.

Return type:bool
cosmk.sourcetree.repo_root_path()[source]

Guess the repo root directory path from the current working directory or (if the CWD does not seem to be a repo root) from the location of the cosmk module.

Return type:str
cosmk.sourcetree.snapshot_manifest(use_branches=False, snapshot_groups=None, no_snapshot_groups=None)[source]

Snapshot the repo manifest file to the current state of the CLIP OS source tree.

Return type:None

cosmk.sdk module

CLIP OS toolkit SDK class

class cosmk.sdk.Sdk(recipe, cwd='/', env=None, additional_capabilities=None, additional_device_bindings=None, prelude_commands=None, postlude_commands=None, writable_assets_dirs_at_build=None)[source]

Bases: object

A CLIP OS toolkit SDK

bootstrap(rootfs_archive, steps=None, env=None)[source]

Bootstrap a SDK from the rootfs archive file specified in the recipe configuration file with the suitable script in order to produce a squashfs image that can be run as a container with the Container class.

Return type:None
container_mountpoints(action_name, action_targeted_recipe, writable_repo_root=False)[source]

Returns the list of ContainerMountpoint’s corresponding to the mountpoints of the SDK context.

Return type:List[ContainerMountpoint]
interactive_run(steps, env=None, shared_host_netns=True, writable_repo_root=False)[source]

Run a command interactively in this SDK

Return type:None
session(action_name, action_targeted_recipe, writable_repo_root=False, terminal=False, env=None, shared_host_netns=False)[source]

Creates an SDK session from this SDK recipe in order to be able to spawn the appropriate container (i.e. for treating a given action for a given recipe of the product product) and pass commands to it.

This context manager is in charge of creating the container (in the sense of the Container class) for the living time span of the context manager.

Return type:Iterator[SdkSession]
class cosmk.sdk.SdkSession(container_session, cwd, env, terminal=False)[source]

Bases: object

Session of a SDK container.

run(command)[source]

Run a command in this SDK container session.

Return type:None

cosmk.virt module

This module manages all the code logic relative to the creation and management of the CLIP OS virtualized environments with libvirt.

class cosmk.virt.VirtualizedEnvironment(name, libvirt_domain_xml_template, libvirt_network_xml_template, qcow2_main_disk_image, ovmf_firmware_code, ovmf_firmware_vars_template)[source]

Bases: object

A CLIP OS recipe virtualized environment.

Parameters:
  • name (str) – the name to give to the libvirt domain and network
  • libvirt_domain_xml_template (str) – the path to the XML template file to use as the XML domain definition for the libvirt domain
  • libvirt_network_xml_template (str) – the path to the XML template file to use as the XML network definition for the libvirt network
  • qcow2_main_disk_image (str) – the path to the main disk image (formatted as QCOW2) to use for the libvirt domain to be created
  • ovmf_firmware_code (str) – the path to the OVMF firmware code to be used by the libvirt domain
  • ovmf_firmware_vars_template (str) – the path to the OVMF firmware UEFI vars template file to be used by the libvirt domain
RUNTIME_WORKING_DIR_REPO_SUBPATH = 'run/virtual_machines'
create(start=False, destroy_preexisting=False)[source]

Create the virtualized environment in libvirt with its dedicated working directory in the sub-path in repo (defined in RUNTIME_WORKING_DIR_REPO_SUBPATH).

Return type:None
destroy()[source]

Destroy the virtualized environment in libvirt with its dedicated working directory in the sub-path in repo (defined in RUNTIME_WORKING_DIR_REPO_SUBPATH).

Return type:None
spawn_virt_manager_console()[source]

Spawn a virtual machine manager console for the virtual machine.

Return type:None
cosmk.virt.guess_external_netiface_name()[source]

Tries to retrieve the name of the external network interface. To do so, this function select the first returned network interface whose name suggest to be an Ethernet or wireless interface (en*, eth* or wl*) and which appears to be connected to a full-duplex medium.

Raises:VirtualizedEnvironmentError – if no external network inteface could be guessed and no dummy value has been provided
Return type:str