iocage_lib package

Submodules

iocage_lib.ioc_check module

Check datasets before execution

class iocage_lib.ioc_check.IOCCheck(silent=False, callback=None, migrate=False, reset_cache=False)

Bases: object

Checks if the required iocage datasets are present

iocage_lib.ioc_clean module

Destroy all of a dataset type.

class iocage_lib.ioc_clean.IOCClean(callback=None, silent=False)

Bases: object

Cleans datasets and snapshots of a given type.

clean_all()

Cleans everything related to iocage.

clean_debug()

Removes the debug directory

clean_images()

Destroys the images dataset

clean_jails()

Cleans all jails and their respective snapshots.

clean_releases()

Cleans all releases and the jails created from them.

clean_templates()

Cleans all templates and their respective children.

iocage_lib.ioc_common module

Common methods we reuse.

iocage_lib.ioc_common.boolean_prop_exists(supplied_props, props_to_check)

iocage_lib.ioc_common.callback(_log, callback_exception)

Helper to call the appropriate logging level

iocage_lib.ioc_common.check_release_newer(release, callback=None, silent=False, raise_error=True, major_only=False)

Checks if the host RELEASE is greater than the target release

iocage_lib.ioc_common.check_truthy(value)

Checks if the given value is ‘True’

iocage_lib.ioc_common.checkoutput(*args, **kwargs)

Just a wrapper to return utf-8 from check_output

iocage_lib.ioc_common.construct_truthy(item, inverse=False)

Will return an iterable with all truthy variations

iocage_lib.ioc_common.consume_and_log(exec_gen, log=True, callback=None)

Consume a generator and massage the output with lines

iocage_lib.ioc_common.copytree(src, dst, symlinks=False, ignore=None)

Copies a tree and overwrites.

iocage_lib.ioc_common.gen_nat_ip(ip_prefix)

Best effort to try to allocate a private NAT IP for a jail

iocage_lib.ioc_common.gen_unused_lo_ip()

Best effort to try to allocate a localhost IP for a jail

iocage_lib.ioc_common.generate_devfs_ruleset(conf, paths=None, includes=None, callback=None, silent=False)

Will add a per jail devfs ruleset with the specified rules, specifying defaults that equal devfs_ruleset 4

iocage_lib.ioc_common.get_active_jails()

iocage_lib.ioc_common.get_host_gateways()

iocage_lib.ioc_common.get_host_release()

Helper to return the hosts sanitized RELEASE

iocage_lib.ioc_common.get_jail_freebsd_version(path, release)

Checks the current patch level for the jail

iocage_lib.ioc_common.get_jails_with_config(filters=None, mapping_func=None)

iocage_lib.ioc_common.get_name_sortkey(name)

iocage_lib.ioc_common.get_natural_sortkey(text)

iocage_lib.ioc_common.get_nested_key(_dict, keys=None)

Gets a nested key from a dictionary.

iocage_lib.ioc_common.get_size_sortkey(size)

iocage_lib.ioc_common.get_used_ips()

Run ifconfig in every jail and return an iteratable of the inuse addresses

iocage_lib.ioc_common.ioc_sort(caller, s_type, data=None)

iocage_lib.ioc_common.logit(content, _callback=None, silent=False, exception=<class 'RuntimeError'>)

Helper to check callable status of callback or call ours.

iocage_lib.ioc_common.lowercase_set(values)

iocage_lib.ioc_common.match_to_dir(iocroot, uuid, old_uuid=None)

Checks for existence of jail/template with specified uuid. Replaces dots and underscores in the uuid with pattern [._] and returns the template- or jail directory that matches, or returns None if no match was found. Background: jail(8) doesn’t allow dots in the name, they will be replaced with underscores. Because of this, foo.bar and foo_bar will be considered identical, as they cannot coexist.

iocage_lib.ioc_common.open_atomic(filepath, *args, **kwargs)

Open temporary file object that atomically moves to destination upon exiting.

Allows reading and writing to and from the same filename.

The file will not be moved to destination in case of an exception.

Parameters

filepathstring

the file path to be opened

fsyncbool

whether to force write the file to disk

*argsmixed

Any valid arguments for open

**kwargsmixed

Any valid keyword arguments for open

iocage_lib.ioc_common.parse_latest_release()

Returns the latest RELEASE from upstreams supported list

iocage_lib.ioc_common.parse_package_name(pkg)

iocage_lib.ioc_common.raise_sort_error(sort_list)

iocage_lib.ioc_common.retrieve_admin_portals(conf, jail_running, admin_portal, default_gateways=None, full_ipv4_dict=None)

iocage_lib.ioc_common.retrieve_ip4_for_jail(conf, jail_running)

iocage_lib.ioc_common.runscript(script, custom_env=None)

Runs the script provided and return a tuple with first value showing stdout and last showing stderr

iocage_lib.ioc_common.set_interactive(interactive)

Returns True or False if stdout is a tty

iocage_lib.ioc_common.set_rcconf(jail_path, key, value)

iocage_lib.ioc_common.sort_ava(ava)

Sort df by AVA

iocage_lib.ioc_common.sort_boot(boot)

Sort the list by boot, then by name.

iocage_lib.ioc_common.sort_created(crt)

Sort snaplist by CREATED

iocage_lib.ioc_common.sort_crt(crt)

Sort df by CRT

iocage_lib.ioc_common.sort_ip(sort_row, version='4')

Sort the list by IP address We expect the following values for ip sorting 1) interface|ip/subnet 2) interface|ip 3) interface|dhcp 4) ip 5) ip|accept_rtadv

All the while obviously not forgetting that there can be multiple ips specified by ‘,’ delimiter

iocage_lib.ioc_common.sort_ip6(ip)

Helper for sort_ip

iocage_lib.ioc_common.sort_jid(jid)

Sort the list by JID.

iocage_lib.ioc_common.sort_key(item)

Sort list by the first key.

iocage_lib.ioc_common.sort_name(name)

Sort list by the name.

iocage_lib.ioc_common.sort_qta(qta)

Sort df by QTA or snaplist by USED

iocage_lib.ioc_common.sort_release(releases, split=False, fetch_releases=False)

Sort the list by RELEASE, if split is true it’s expecting full datasets.

iocage_lib.ioc_common.sort_res(res)

Sort df by RES or snaplist by RSIZE

iocage_lib.ioc_common.sort_state(state)

Sort the list by state, then by name.

iocage_lib.ioc_common.sort_template(template)

Helper function for templates to be sorted in sort_name

iocage_lib.ioc_common.sort_type(jail_type)

Sort the list by jail type, then by name.

iocage_lib.ioc_common.sort_use(use)

Sort df by USE

iocage_lib.ioc_common.tempfile(suffix='', dir=None)

Context for temporary file.

Will find a free temporary filename upon entering and will try to delete the file on leaving, even in case of an exception.

Parameters

suffixstring

optional file suffix

dirstring

optional directory to save temporary file in

iocage_lib.ioc_common.tmp_dataset_checks(_callback, silent)

iocage_lib.ioc_common.truthy_inverse_values()

iocage_lib.ioc_common.truthy_values()

iocage_lib.ioc_common.try_convert(value, default, *types)

iocage_lib.ioc_common.validate_plugin_manifest(manifest, _callback, silent)

iocage_lib.ioc_create module

iocage create module.

class iocage_lib.ioc_create.IOCCreate(release, props, num, pkglist=None, plugin=False, migrate=False, config=None, silent=False, template=False, short=False, basejail=False, thickjail=False, empty=False, uuid=None, clone=False, thickconfig=False, clone_basejail=False, callback=None)

Bases: object

Create a jail from a clone.

create_config(jail_uuid, release, source_template)

Create the jail configuration with the minimal needed defaults. If self.thickconfig is True, it will create a jail with all properties.

create_install_packages(jail_uuid, location, repo='pkg.freebsd.org')

Takes a list of pkg’s to install into the target jail. The resolver property is required for pkg to have network access.

create_jail()

Helper to catch SIGINT

create_rc(location, host_hostname, basejail=0)

Writes a boilerplate rc.conf file for a jail if it doesn’t exist,

otherwise changes the hostname.

create_thickjail(jail_uuid, source)

iocage_lib.ioc_debug module

This collects debug about all the iocage jails.

class iocage_lib.ioc_debug.IOCDebug(path, silent=False, callback=None)

Bases: object

Collects the following debug for a system + jails/templates:

zfs list mount df -h

iocage get all /etc/hosts /etc/rc.conf /etc/nsswitch.conf ifconfig -a netstat -nr /etc/resolv.conf

run_debug()

run_host_debug()

run_jail_debug(name, path)

iocage_lib.ioc_destroy module

iocage destroy module.

class iocage_lib.ioc_destroy.IOCDestroy(callback=None)

Bases: object

Destroy a jail’s datasets and then if they have a RELEASE snapshot, destroy that as well.

destroy_jail(path, clean=False)

A convenience wrapper to call __stop_jails__ and

__destroy_parse_datasets__

iocage_lib.ioc_exceptions module

Exception classes for iocage

exception iocage_lib.ioc_exceptions.CommandFailed(message)

Bases: ExceptionWithMsg

exception iocage_lib.ioc_exceptions.CommandNeedsRoot(message)

Bases: ExceptionWithMsg

exception iocage_lib.ioc_exceptions.ExceptionWithMsg(message)

Bases: Exception

message attribute will be an iterable if a message is supplied

exception iocage_lib.ioc_exceptions.Exists(message)

Bases: ExceptionWithMsg

exception iocage_lib.ioc_exceptions.JailCorruptConfiguration(message)

Bases: JailMisconfigured

exception iocage_lib.ioc_exceptions.JailMisconfigured(message)

Bases: ExceptionWithMsg

exception iocage_lib.ioc_exceptions.JailMissingConfiguration(message)

Bases: JailMisconfigured

exception iocage_lib.ioc_exceptions.JailRunning

Bases: Exception

exception iocage_lib.ioc_exceptions.PoolNotActivated

Bases: Exception

exception iocage_lib.ioc_exceptions.ValidationFailed(message)

Bases: ExceptionWithMsg

exception iocage_lib.ioc_exceptions.ValueNotFound

Bases: Exception

iocage_lib.ioc_exceptions.ignore_exceptions(*exceptions, clean=None, suppress_exception=True)

Ignore any exceptions specified by exceptions and make sure that we clean any resources specified by callable clean

iocage_lib.ioc_exec module

iocage exec module.

class iocage_lib.ioc_exec.IOCExec(command, path, uuid='', host_user='root', jail_user=None, plugin=False, unjailed=False, skip=False, stdin_bytestring=None, su_env=None, decode=False, callback=None)

Bases: object

Run jexec with a user inside the specified jail.

exec_jail()

flight_checks()

class iocage_lib.ioc_exec.InteractiveExec(*args, **kwargs)

Bases: IOCExec

class iocage_lib.ioc_exec.SilentExec(*args, **kwargs)

Bases: object

iocage_lib.ioc_fetch module

iocage fetch module.

class iocage_lib.ioc_fetch.IOCFetch(release, server='download.freebsd.org', user='anonymous', password='anonymous@', auth=None, root_dir=None, http=True, _file=False, verify=True, hardened=False, update=True, eol=True, files=('MANIFEST', 'base.txz', 'lib32.txz', 'src.txz'), silent=False, callback=None)

Bases: object

Fetch a RELEASE for use as a jail base.

fetch_download(_list, missing=False)

Creates the download dataset and then downloads the RELEASE.

fetch_extract(f)

Takes a src and dest then creates the RELEASE dataset for the data.

fetch_http_release(eol, _list=False)

Fetch a user specified RELEASE from FreeBSD’s http server or a user supplied one. The user can also specify the user, password and root-directory containing the release tree that looks like so:

• XX.X-RELEASE

• XX.X-RELEASE

• XX.X-RELEASE

fetch_release(_list=False)

Small wrapper to choose the right fetch.

fetch_update(cli=False, uuid=None)

This calls ‘freebsd-update’ to update the fetched RELEASE.

update_progress(progress, display_text, elapsed, chunk_size)

Displays or updates a console progress bar. Original source: https://stackoverflow.com/a/15860757/1391441

iocage_lib.ioc_fetch.untar_release_filter(member, dest_path)

iocage_lib.ioc_fstab module

Manipulate a jails fstab

class iocage_lib.ioc_fstab.Fstab

Bases: Structure

fs_file

Structure/Union member

fs_freq

Structure/Union member

fs_mntops

Structure/Union member

fs_passno

Structure/Union member

fs_spec

Structure/Union member

fs_type

Structure/Union member

fs_vfstype

Structure/Union member

class iocage_lib.ioc_fstab.IOCFstab(uuid, action, source='', destination='', fstype='', fsoptions='', fsdump='', fspass='', index=None, silent=False, callback=None, header=False)

Bases: object

Will add or remove an entry, and mount or umount the filesystem.

fstab_list()

Returns list of lists, or a table

iocage_lib.ioc_image module

iocage export and import module

class iocage_lib.ioc_image.IOCImage(callback=None, silent=False)

Bases: object

export() and import()

export_jail(uuid, path, compression_algo='zip')

Make a recursive snapshot of the jail and export to a file.

import_jail(jail, compression_algo=None, path=None)

Import from an iocage export.

iocage_lib.ioc_json module

Convert, load or write JSON.

class iocage_lib.ioc_json.IOCConfiguration(location, checking_datasets, silent, callback)

Bases: object

backup_iocage_jail_conf(location)

check_config(conf, default=False)

Takes JSON as input and checks to see what is missing and adds the new keys to the defaults with their default values if missing.

check_default_config()

This sets up the default configuration for jails.

check_jail_config(conf)

Checks the jails configuration and migrates anything needed

fix_properties(conf)

Takes a conf file and makes sure any property that has a bad value that was previously allowed is fixed to the correct equivalent, but aren’t a CONFIG_VERSION bump

Returns a bool if it updated anything and it needs writing

static get_mac_prefix()

get_pool_and_iocroot()

For internal getting of pool and iocroot.

static get_version()

Sets the iocage configuration version.

json_write(data, _file='/config.json', defaults=False)

Write a JSON file at the location given with supplied data.

static retrieve_default_props()

static validate_mac_prefix(mac_prefix)

class iocage_lib.ioc_json.IOCCpuset(name)

Bases: object

static retrieve_cpu_sets()

set_cpuset(value=None)

static validate_cpuset_prop(value, raise_error=True)

class iocage_lib.ioc_json.IOCJson(location='', silent=False, cli=False, stop=False, checking_datasets=False, suppress_log=False, callback=None)

Bases: IOCConfiguration

Migrates old iocage configurations(UCL and ZFS Props) to the new JSON format, will set and get properties.

default_only_props = ['nat_prefix', 'nat_interface', 'nat_backend']

get_full_config()

json_check_prop(key, value, conf, default=False)

Checks if the property matches known good values, if it’s the CLI, deny setting any properties not in this list.

json_convert_from_ucl()

Convert to JSON. Accepts a location to the ucl configuration.

json_convert_from_zfs(uuid, skip=False)

Convert to JSON. Accepts a jail UUID

json_get_value(prop, default=False)

Returns a string with the specified prop’s value.

json_load()

Load the JSON at the location given. Returns a JSON object.

json_migrate_uuid_to_tag(uuid, tag, state, conf)

This will migrate an old uuid + tag jail to a tag only one

json_plugin_get_value(prop)

json_plugin_load()

json_plugin_set_value(prop)

json_set_value(prop, _import=False, default=False)

Set a property for the specified jail.

truthy_props = ['bpf', 'template', 'host_time', 'basejail', 'dhcp', 'vnet', 'rtsold', 'jail_zfs', 'hostid_strict_check', 'boot', 'exec_clean', 'mount_linprocfs', 'mount_procfs', 'allow_vmm', 'allow_tun', 'allow_socket_af', 'allow_quotas', 'allow_mount_zfs', 'allow_mount_tmpfs', 'allow_mount_procfs', 'allow_mount_nullfs', 'allow_mount_fusefs', 'allow_mount_devfs', 'allow_mount_fdescfs', 'allow_mount_linprocfs', 'allow_mount_linsysfs', 'allow_mount', 'allow_mlock', 'allow_chflags', 'allow_raw_sockets', 'allow_sysvipc', 'allow_set_hostname', 'allow_nfsd', 'mount_fdescfs', 'mount_devfs', 'ip6_saddrsel', 'ip4_saddrsel', 'ip_hostname', 'assign_localhost', 'nat']

class iocage_lib.ioc_json.IOCRCTL(name)

Bases: object

rctl_rules_exist(prop=None)

remove_rctl_rules(props=None)

set_rctl_rules(props)

types = {'coredumpsize', 'cputime', 'datasize', 'maxproc', 'memorylocked', 'memoryuse', 'msgqqueued', 'msgqsize', 'nmsgq', 'nsem', 'nsemop', 'nshm', 'nthr', 'openfiles', 'pcpu', 'pseudoterminals', 'readbps', 'readiops', 'shmsize', 'stacksize', 'swapuse', 'vmemoryuse', 'wallclock', 'writebps', 'writeiops'}

static validate_rctl_props(prop, value)

static validate_rctl_tunable()

class iocage_lib.ioc_json.JailRuntimeConfiguration(jail_name, data=None)

Bases: object

normalize_data(data)

property path

remove(key)

set(key, value=None)

sync_changes()

iocage_lib.ioc_list module

List all datasets by type

class iocage_lib.ioc_list.IOCList(lst_type='all', hdr=True, full=False, _sort=None, silent=False, callback=None, plugin=False, quick=False, **kwargs)

Bases: object

List jails that are a specified type.

Format is:

JID UID BOOT STATE TYPE IP4 RELEASE

list_all(jails)

List all jails.

list_all_quick(jails)

Returns a table of jails with minimal processing

list_bases(datasets)

Lists all bases.

list_datasets()

Lists the datasets of given type.

classmethod list_get_jid(uuid)

Return a tuple containing True or False and the jail’s id or ‘-‘.

iocage_lib.ioc_plugin module

iocage plugin module

class iocage_lib.ioc_plugin.IOCPlugin(release=None, jail=None, plugin=None, branch=None, keep_jail_on_failure=False, callback=None, silent=False, **kwargs)

Bases: object

This is responsible for the general life cycle of a plugin jail. This includes creation, updating and upgrading.

DEFAULT_PROPS = {'boot': 1, 'vnet': 1}

PLUGIN_VERSION = '2'

static expand_abi_with_specified_release(packagesite, release)

fetch_plugin(props, num, accept_license)

Helper to fetch plugins

fetch_plugin_index(props, _list=False, list_header=False, list_long=False, accept_license=False, icon=False, official=False, index_only=False)

static fetch_plugin_packagesites(package_sites)

fetch_plugin_versions()

static fetch_plugin_versions_from_plugin_index(plugins_index)

pull_clone_git_repo(depth=None)

static retrieve_plugin_index_data(plugin_index_path, expand_abi=True)

retrieve_plugin_json()

start_rc()

stop_rc()

update(jid)

upgrade(jid)

iocage_lib.ioc_start module

This is responsible for starting jails.

class iocage_lib.ioc_start.IOCStart(uuid, path, silent=False, callback=None, is_depend=False, unit_test=False, suppress_exception=False, used_ports=None)

Bases: object

Starts jails, the network stack for the jail and generates a resolv file

for them. It also finds any scripts the user supplies for exec_*

check_aliases(ip_addrs, mode='4')

Check if the alias already exists for given IP’s, otherwise add default interface to the ips and return the new list

find_bridge_mtu(bridge)

get_bridge_members(bridge)

get_default_gateway(address_family='ipv4')

get_default_interface()

start_copy_localtime()

start_generate_resolv()

start_network(vnet, nat=False)

This function is largely a check to see if VNET is true, and then to actually run the correct function, otherwise it passes.

Parameters:

vnet – Boolean

start_network_interface_vnet(nic_defs, net_configs, jid, nat_addr=0)

Start VNET on interface

Parameters:

• nic_defs – comma separated interface definitions (nic:bridge, nic:bridge…)

• net_configs – Tuple of IP address and router pairs

• jid – The jails ID

start_network_vnet_addr(iface, ip, defaultgw, ipv6=False)

Add an IP address to a vnet interface inside the jail.

Parameters:

• iface – The interface to use

• ip – The IP address to assign

• defaultgw – The gateway IP to assign to the nic

Returns:

If an error occurs it returns the error. Otherwise, it’s None

start_network_vnet_iface(nic, bridge, mtu, jid, nat_addr=0)

The real meat and potatoes for starting a VNET interface.

Parameters:

• nic – The network interface to assign the IP in the jail

• bridge – The bridge to attach the VNET interface

• mtu – The mtu of the VNET interface

• jid – The jails ID

Returns:

If an error occurs it returns the error. Otherwise, it’s None

iocage_lib.ioc_stop module

This stops jails.

class iocage_lib.ioc_stop.IOCStop(uuid, path, silent=False, callback=None, force=False, suppress_exception=False)

Bases: object

Stops a jail and unmounts the jails mountpoints.

iocage_lib.ioc_upgrade module

iocage upgrade module

class iocage_lib.ioc_upgrade.IOCUpgrade(new_release, path, interactive=True, silent=False, callback=None)

Bases: object

Will upgrade a jail to the specified RELEASE.

upgrade_basejail(snapshot=True, snap_name=None)

upgrade_jail()

iocage_lib.iocage module

class iocage_lib.iocage.IOCage(jail=None, rc=False, callback=None, silent=False, activate=False, skip_jails=False, reset_cache=False)

Bases: object

activate(zpool)

Activates the zpool for iocage usage

chroot(command)

Deprecated: Chroots into a jail and runs a command, or the shell.

clean(d_type)

Destroys all of a specified dataset types.

create(release, props, count=0, pkglist=None, template=False, short=False, _uuid=None, basejail=False, thickjail=False, empty=False, clone=None, skip_batch=False, thickconfig=False, clone_basejail=False)

Creates the jail dataset

deactivate(zpool)

debug(directory)

destroy_jail(force=False)

Destroys the supplied jail, to reduce perfomance hit, call IOCage with skip_jails=True

destroy_release(download=False)

Destroy supplied RELEASE and the download dataset if asked

df()

Returns a list containing the resource usage of all jails

exec(command, host_user='root', jail_user=None, console=False, start_jail=False, interactive=False, unjailed=False, msg_return=False)

Executes a command in the jail as the supplied users.

exec_all(command, host_user='root', jail_user=None, console=False, start_jail=False, interactive=False, unjailed=False, msg_return=False)

Runs exec for all jails

export(compression_algo='zip')

Will export a jail

fetch(**kwargs)

Fetches a release or plugin.

fstab(action, source, destination, fstype, options, dump, _pass, index=None, add_path=False, header=False)

Adds an fstab entry for a jail

get(prop, recursive=False, plugin=False, pool=False, start_jail=False)

Get a jail property

import_(compression_algo='zip', path=None)

Imports a jail

list(lst_type, header=False, long=False, sort='name', uuid=None, plugin=False, quick=False, **kwargs)

Returns a list of lst_type

rename(new_name)

static reset_cache()

restart(soft=False)

rollback(name)

Rolls back a jail and all datasets to the supplied snapshot

set(prop, plugin=False, rename=False)

Sets a property for a jail or plugin

snap_list(long=True, _sort='created')

Gathers a list of snapshots and returns it

snap_list_all(long, _sort)

snap_remove(snapshot, cloned_datasets=None)

Removes user supplied snapshot from jail

snap_remove_all(snapshot)

snapshot(name)

Will create a snapshot for the given jail

snapshot_all(name)

start(jail=None, ignore_exception=False, used_ports=None)

Checks jails type and existence, then starts the jail

stop(jail=None, force=False, ignore_exception=False)

Stops the jail.

update(pkgs=False, server=None, verify=True)

Updates a jail to the latest patchset.

update_all(pkgs=False)

Runs update for all jails

upgrade(release)

upgrade_all(release)

Runs upgrade for all jails

class iocage_lib.iocage.PoolAndDataset

Bases: object

get_iocroot()

Helper to get the iocroot.

Return:

string: with the iocroot name.

get_pool()

Helper to get the current pool.

Return:

string: with the pool name.

Module contents