libioc.Jail module

A Jail defines the configuration of a FreeBSD jail managed by ioc.

It consists of kernel state and configuration assets (config.json).

Configuration values are in a JailConfig, that maps the Jail configuration to permanent disk storage. The latest version used a config.json JSON config file. For compatibility with older versions of iocage (shell), UCL config files and storage as ZFS properties on the jails ZFS dataset are supported as well.

The state of a Jail is managed by the kernel, that ioc interfaces with libc.

class libioc.Jail.Jail(data={}, dataset=None, dataset_name=None, config_type='auto', config_file=None, logger=None, zfs=None, host=None, fstab=None, root_datasets_name=None, new=False, skip_invalid_config=False)[source]

Bases: libioc.Jail.JailGenerator

Synchronous wrapper of JailGenerator.

destroy(force=False)[source]

Destroy a Jail and it’s datasets.

Parameters

force (bool) – (default=False) This flag enables whether an existing jail should be shut down before destroying the dataset. By default destroying a jail requires it to be stopped.

Return type

List[IocEvent]

fork_exec(command, passthru=False, event_scope=None, dependant_jails_seen=[], start_dependant_jails=True, **temporary_config_override)[source]

Start a jail, run a command and shut it down immediately.

Parameters

  • command (string) – The command to execute in the jail.

  • passthru (bool) – Execute commands in an interactive shell.

  • event_scope (libioc.events.Scope) –

    (default=None)

    Provide an existing libiocage event scope or automatically create a new one instead.

  • dependant_jails_seen (list[libioc.JailGenerator]) – Jail depends can have circular dependencies. By passing a list of already started jails to the start command, iocage does not need to query their state, because they are known to be running already. This argument is internally used when starting a jails dependants recursively.

  • start_dependant_jails (bool) – When disabled, no dependant jails will be started.

  • **temporary_config_override (dict(str, any)) –

    Other named arguments temporary override JailConfig properties.

    For example:

    jail = libioc.JailGenerator(“myjail”) events = jail.fork_exec(“ifconfig”, vnet=False) print(list(events))

Return type

str

rename(*args, **kwargs)[source]

Rename the jail.

Return type

List[IocEvent]

start(*args, **kwargs)[source]

Start the jail.

Return type

List[IocEvent]

stop(*args, **kwargs)[source]

Stop the jail.

Return type

List[IocEvent]

class libioc.Jail.JailGenerator(data={}, dataset=None, dataset_name=None, config_type='auto', config_file=None, logger=None, zfs=None, host=None, fstab=None, root_datasets_name=None, new=False, skip_invalid_config=False)[source]

Bases: libioc.Jail.JailResource

iocage unit orchestrates a jail’s configuration and manages state.

Jails are represented as a zfs dataset zpool/iocage/jails/<NAME>

Directory Structure:

zpool/iocage/jails/<NAME>:

The jail’s dataset containing it’s configuration and root dataset. iocage-legacy used to store a jails configuration as ZFS properties on this dataset. Even though the modern JSON config mechanism is preferred.

zpool/iocage/jails/<NAME>/root:

This directory is the dataset used as jail’s root when starting a jail. Usually the clone source of a root dataset is a snapshot of the release’s root dataset.

zpool/iocage/jails/<NAME>/config.json:

Jails configured with the latest configuration style store their information in a JSON file. When this file is found in the jail’s dataset, libiocage assumes the jail to be a JSON-style jail and ignores other configuration mechanisms.

zpool/iocage/jails/<NAME>/config:

Another compatible configuration mechanism is a UCL file. It’s content is only taken into account if no JSON or ZFS configuration was found.

Jail Types:

Standalone:

The /root dataset gets cloned from a release at creation time. It it not affected by changes to the Release and persists all data within the jail.

NullFS Basejail:

The fastest method to spawn a basejail by mounting read-only directories from the release’s root dataset by creating a snapshot of the release on each boot of the jail. When a release is updated, the jail is updated as well on the next reboot. This type is the one used by the Python implementation of libioc.

ZFS Basejail: Legacy basejails used to clone individual datasets from a

release (stored in zpool/iocage/base/<RELEASE>).

clone_from_jail(source_jail, event_scope=None)[source]

Create a Jail from another Jail.

Return type

Generator[IocEvent, None, None]

clone_to_dataset(destination_dataset_name, delete_existing=False, event_scope=None)[source]

Clones the jails dataset to another dataset with the given name.

Return type

Generator[IocEvent, None, None]

create(resource=None)[source]

Create a Jail from a given Resource.

Parameters

resource (Jail or Release) – The (new) jail is created from this resource. If no resource is specified, an empty dataset will be created

Return type

None

create_from_release(release)[source]

Create a Jail from a Release.

Parameters

resource (Release) – The jail is created from the provided resource. This can be either another Jail or a Release.

Return type

None

create_from_scratch()[source]

Create a new jail without any root dataset content.

Return type

None

create_from_template(template)[source]

Create a Jail from a template Jail.

Return type

None

destroy(force=False, force_stop=False, event_scope=None)[source]

Destroy a Jail and it’s datasets.

Parameters

  • force (bool) – (default=False) This flag enables whether an existing jail should be shut down before destroying the dataset. By default destroying a jail requires it to be stopped.

  • force_stop (bool) – (default=False) A jail is force stopped when either the force_stop argument was set or the force option was enabled and the jail is running. When being enabled the argument invokes a full stop before destroying the jail.

Return type

Generator[IocEvent, None, None]

property devfs_ruleset

Return the number of the jail’s devfs ruleset.

When a new combination of the base ruleset specified in jail.config[“devfs_ruleset”] and rules automatically added by iocage appears, the according rule is automatically created and added to the /etc/devfs.rules file on the host

Users may reference a rule by numeric identifier or name. This numbers are automatically selected, so it’s advisable to use names.1

Return type

DevfsRuleset

property env

Return the environment variables for hook scripts.

Return type

Dict[str, str]

exec(command, env={}, passthru=False, **kwargs)[source]

Execute a command in a running jail.

Parameters

  • command (list) –

    A list of command and it’s arguments

    Example: [“/usr/bin/whoami”]

  • env (dict) – The dictionary may contain env variables that will be forwarded to the executed jail command.

  • passthru (bool) –

    (default=False)

    When enabled the commands stdout and stderr are directory forwarded to the attached terminal. The results will not be included in the CommandOutput, so that (None, None, <returncode>) is returned.

Return type

Tuple[Optional[str], Optional[str], int]

exec_console()[source]

Shortcut to drop into a shell of a started jail.

Return type

Tuple[Optional[str], Optional[str], int]

fork_exec(command, passthru=False, event_scope=None, start_dependant_jails=True, dependant_jails_seen=[], env={}, **temporary_config_override)[source]

Start a jail, run a command and shut it down immediately.

Parameters

  • command (string) – The command to execute in the jail.

  • passthru (bool) – Execute commands in an interactive shell.

  • event_scope (libioc.events.Scope) –

    (default=None)

    Provide an existing libiocage event scope or automatically create a new one instead.

  • dependant_jails_seen (list[libioc.JailGenerator]) – Jail depends can have circular dependencies. By passing a list of already started jails to the start command, iocage does not need to query their state, because they are known to be running already. This argument is internally used when starting a jails dependants recursively.

  • start_dependant_jails (bool) – When disabled, no dependant jails will be started.

  • **temporary_config_override (dict(str, any)) –

    Other named arguments temporary override JailConfig properties.

    For example:

    jail = libioc.JailGenerator(“myjail”) events = jail.fork_exec(“ifconfig”, vnet=False) print(list(events))

Return type

Generator[IocEvent, None, None]

property full_name

Return the full identifier of a jail.

When more than one root dataset is managed by iocage, the full source and name are returned. Otherwise just the name.

For example mydataset/jailname or just jailname.

Return type

str

get_hook_script_path(hook_name)[source]

Return the absolute path to the hook script file.

Return type

str

property hostid_check_ok

Return true if the hostid check passes.

Return type

bool

property humanreadable_name

Return the human-readable identifier to print in logs and CLI output.

Whenever a Jail is found to have a UUID as identifier, a shortened string of the first 8 characters is returned

Return type

str

property identifier

Return the jail id used in snapshots, jls, etc.

Return type

str

property is_basejail

Return True if a Jail is a basejail.

If this is the case, parts of the jails dataset will be mounted from its release or upstream Jail (for example a Template)

Return type

bool

property jid

Return a jails JID if it is running or None.

Return type

Optional[int]

property launch_script_dir

Return the launch-scripts directory path of the jail.

Return type

str

property name

Return the configured jail id.

Return type

str

property networks

Return the list of a jails configured networks.

Return type

List[Network]

passthru(command, env=None)[source]

Execute a command in a started jail and passthrough STDIN and STDOUT.

command (list):

A list of command and it’s arguments

Example: [“/bin/sh”]

Return type

Tuple[Optional[str], Optional[str], int]

promote()[source]

Promote all datasets of the jail.

Return type

None

property provisioner

Return the jails Provisioner instance.

The provisioner itself is going to interpret the jails configuration dynamically, so that the Provisioner instance can be memoized.

query_jid()[source]

Invoke update of the jails JID.

Return type

None

property release

Return the libioc.Release instance linked with the jail.

Return type

ReleaseGenerator

property release_snapshot

Return the matching release verion snaphsot.

Return type

ZFSSnapshot

rename(new_name, event_scope=None)[source]

Change the name of a jail.

Parameters

new_name (str) – The new name of a jail. It might not be used by another Jail and must differ from the current name.

Return type

Generator[IocEvent, None, None]

require_jail_existing(log_errors=True)[source]

Raise JailDoesNotExist exception if the jail does not exist.

Return type

None

require_jail_is_template(log_errors=True)[source]

Raise JailIsTemplate exception if the jail is a template.

Return type

None

require_jail_match_hostid(log_errors=True)[source]

Raise JailIsTemplate exception if the jail is a template.

Return type

None

require_jail_not_existing(log_errors=True)[source]

Raise JailAlreadyExists exception if the jail already exists.

Return type

None

require_jail_not_template(log_errors=True)[source]

Raise JailIsTemplate exception if the jail is a template.

Return type

None

require_jail_running(log_errors=True)[source]

Raise JailNotRunning exception if the jail is stopped.

Return type

None

require_jail_stopped(log_errors=True)[source]

Raise JailAlreadyRunning exception if the jail is running.

Return type

None

require_storage_backend(log_errors=True)[source]

Raise if the jail was not initialized with a storage backend.

Return type

None

restart(shutdown=False, force=False, event_scope=None, env={})[source]

Restart the jail.

Return type

Generator[IocEvent, None, None]

property running

Return True if a jail is running.

Return type

bool

save()[source]

Permanently save a jail’s configuration.

Return type

None

property script_env_path

Return the absolute path to the jail script env file.

Return type

str

start(quick=False, passthru=False, single_command=None, event_scope=None, dependant_jails_seen=[], start_dependant_jails=True, env={})[source]

Start the jail.

Parameters

  • quick (bool) – Skip several operations that are not required when a jail was unchanged since its last start (for example when restarting it).

  • passthru (bool) – Execute commands in an interactive shell.

  • single_command (str) – When set the jail is launched non-persistent. The startup cycle reduces to the prestart, command and poststop hooks with the singe_command being executed in a /bin/sh context.

  • event_scope (libioc.events.Scope) –

    (default=None)

    Provide an existing libiocage event scope or automatically create a new one instead.

  • dependant_jails_seen (list[libioc.JailGenerator]) – Jail depends can have circular dependencies. By passing a list of already started jails to the start command, iocage does not need to query their state, because they are known to be running already. This argument is internally used when starting a jails dependants recursively.

  • start_dependant_jails (bool) – When disabled, no dependant jails will be started.

  • env (dict) – Environment variables that are available in all jail hooks. Existing environment variables (provided by the system or ioc) can be overridden with entries in this dictionary.

Return type

Generator[IocEvent, None, None]

stop(force=False, event_scope=None, log_errors=True, env={})[source]

Stop a jail.

Parameters

  • force (bool) –

    (default=False)

    Ignores failures and enforces teardown if True.

  • event_scope (libioc.events.Scope) –

    (default=None)

    Provide an existing libiocage event scope or automatically create a new one instead.

  • log_errors (bool) –

    (default=True)

    When disabled errors are not passed to the logger. This is useful in scripted contexts when then stop operation was executed to enforce a defined jail state.

  • env (dict) – Environment variables that are available in all jail hooks. Existing environment variables (provided by the system or ioc) can be overridden with entries in this dictionary.

Return type

Generator[IocEvent, None, None]

property stopped

Return True if a jail is stopped.

Return type

bool

property storage_backend

Return the jail storage abstraction class.

Returns the class that represents the jails storage backend according to its configuration.

Return type

Storage

class libioc.Jail.JailResource(jail, dataset=None, dataset_name=None, config_type='auto', config_file=None, logger=None, zfs=None, host=None, fstab=None, root_datasets_name=None)[source]

Bases: libioc.LaunchableResource.LaunchableResource, libioc.VersionedResource.VersionedResource

Resource that represents a jail.

autoset_dataset_name()[source]

Automatically determine and set the dataset_name.

When a jail was created with the new attribute enabled, the dataset might not exist, so that a dataset_name lookup would fail. Calling this method sets the jails dataset_name to a child dataset of the hosts jails dataset with the jails name.

Return type

None

property dataset_name

Name of the jail base ZFS dataset.

If the resource has no dataset or dataset_name assigned yet, the jail id is used to find name the dataset

Return type

str

property fstab

Memoized fstab wrapper of a Jail.

The fstab file is stored in the top level of a Jails dataset

Return type

JailFstab

get(key)[source]

Get a config value from the jail or defer to its resource.

Return type

Any

getstring(key)[source]

Get any resource property as string or ‘-‘.

Returns the string value, or an empty string in case of an unknown user config property.

Parameters

key (string) – Name of the jail property to return

Return type

str

property jail

Jail instance that belongs to the resource.

Usually the resource becomes inherited from the jail itself. It can still be used linked to a foreign jail by passing jail as named attribute to the __init__ function

Return type

JailGenerator

property source

Return the name of the jails source root datasets.

Return type

str