libioc.Datasets module

ioc datasets module.

class libioc.Datasets.Datasets(sources=None, zfs=None, logger=None)[source]

Bases: dict

All source datasets managed by libioc.

Automatically detects activated iocage datasets from ZFS pool properties or sysrc lines in /etc/rc.conf.

Operations that should be performed on selected iocage datasets, are typically achieved by filtering Datasets. Only the matching and activated datasets are then taken into account and thus result in a performance benefit.

The iocage dataset configuration from sysrc wins over ZFS pools activated by the org.freebsd.ioc:active property on their pool root dataset.

ZFS_POOL_ACTIVE_PROPERTY = 'org.freebsd.ioc:active'
activate(mountpoint=None)[source]

Activate the root pool and set the given mountpoint.

Parameters

mountpoint (Optional[AbsolutePath]) – see activate_pool()

Return type

None

activate_pool(pool, mountpoint=None)[source]

Activate the given pool and set its mountpoint.

Pool activation follows the traditional way of setting a ZFS property on the pool that other iocage variants will detect.

The mechanism cannot be combined with iocage datasets defined in /etc/rc.conf, so that using the Multi-Pool feature is not possible. When attemptig to activate a pool on a system with such configuration an ActivationFailed error is raised.

Parameters

  • pool (ZFSPool) – Target of the iocage activation on which an iocage dataset is created on the top level (e.g. zfs create <pool>/iocage)

  • mountpoint (Optional[AbsolutePath]) – The desired mountpoint for the iocage dataset.

Return type

None

property active_pool

Return the currently active iocage pool.

Return type

ZFSPool

attach_root_datasets(source_name, root_datasets)[source]

Attach another RootDatasets object to the iocage scope.

Parameters
Return type

None

attach_source(source_name, dataset_identifier)[source]

Attach a source by its DatasetIdentifier to the iocage scope.

Parameters

  • source_name (str) – Name of the source dataset.

  • dataset_identifier (Union[str, ZFSDataset]) – ZFSDataset structure or dataset name representing the source.

Return type

None

attach_sources(sources)[source]

Attach a sources dictionary at once.

Return type

None

deactivate()[source]

Deactivate a ZFS pool for iocage use.

Return type

None

find_root_datasets(dataset_name)[source]

Return the RootDatasets instance containing the dataset.

Return type

RootDatasets

find_root_datasets_name(dataset_name)[source]

Return the name of the source containing the matching dataset.

Return type

str

get_root_source(source_name=None)[source]

Get the root source with a certain name.

When the source name is empty, the main source is returned.

Return type

Datasets

is_pool_active(pool=None)[source]

Return True if the pool is activated for libioc.

Parameters

pool (Optional[ZFSPool]) – The specified pool is checked for being activated for libioc. When the pool is unset, the main pool is tested against.

Return type

bool

property main

Return the source that was attached first.

Return type

Datasets

class libioc.Datasets.FilteredDatasets(datasets, source_filters=None, zfs=None, logger=None)[source]

Bases: libioc.Datasets.Datasets

A wrapper around Datasets that limits access to certain root datasets.

Parameters

  • datasets (Datasets) – The Datasets hosts instance

  • source_filters (Optional[Tuple[str, …]]) –

    No filters were applied when unset. The names contained in the Tuple are matched against the dataset names specified in rc.conf.

    $ sysrc ioc_dataset_main="zroot/iocage"
$ ioc list --source main

  • zfs (Optional[ZFS]) – The shared ZFS object.

  • logger (Optional[Logger]) – The shared logger instance.

property source_filters

Return the active source filters or None.

Return type

Optional[Tuple[str, …]]

exception libioc.Datasets.RCConfEmptyException[source]

Bases: Exception

Exception for internal use.

class libioc.Datasets.RootDatasets(root_dataset, zfs=None, logger=None)[source]

Bases: object

iocage core dataset abstraction.

Defined by a ZFSDataset and a given name 1, the RootDataset provides access to the iocage source datasets. The ability to handle multiple source datasets, allows nested iocage usage in other jails.

$ sysrc ioc_dataset_ioc="zroot/iocage"
ioc_dataset_ioc:  -> zroot/iocage
$ ioc_dataset_nvme:  -> nvme/my-dataset/iocage
ioc_dataset_nvme:  -> nvme/my-dataset/iocage

When more than one dataset is enabled, Resource names are displayed including their RootDataset prefix (e.g. ioc/myjail).

1

The ZFS property activated default name is ioc

property base

Get or create the iocage ZFS basejail releases dataset.

Return type

ZFSDataset

property jails

Get or create the iocage jails dataset.

Return type

ZFSDataset

property pkg

Get or create the pkg cache.

Return type

ZFSDataset

property releases

Get or create the iocage releases dataset.

Return type

ZFSDataset

libioc.Datasets.filter_datasets(datasets, sources)[source]

Return FilteredDatasets by a tuple of sources.

Return type

FilteredDatasets