OSTree.Sysroot¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`get_deployment_origin_path` (deployment_path)
class	`new` (path)
class	`new_default` ()
	`change_finalization` (deployment)
	`cleanup` (cancellable)
	`cleanup_prune_repo` (options, cancellable)
	`deploy_tree` (osname, revision, origin, provided_merge_deployment, override_kernel_argv, cancellable)
	`deploy_tree_with_options` (osname, revision, origin, provided_merge_deployment, opts, cancellable)
	`deployment_set_kargs` (deployment, new_kargs, cancellable)
	`deployment_set_kargs_in_place` (deployment, kargs_str, cancellable)
	`deployment_set_mutable` (deployment, is_mutable, cancellable)
	`deployment_set_pinned` (deployment, is_pinned)
	`deployment_unlock` (deployment, unlocked_state, cancellable)
	`ensure_initialized` (cancellable)
	`get_booted_deployment` ()
	`get_bootversion` ()
	`get_deployment_directory` (deployment)
	`get_deployment_dirpath` (deployment)
	`get_deployments` ()
	`get_fd` ()
	`get_merge_deployment` (osname)
	`get_path` ()
	`get_repo` (cancellable)
	`get_staged_deployment` ()
	`get_subbootversion` ()
	`init_osname` (osname, cancellable)
	`initialize` ()
	`initialize_with_mount_namespace` (cancellable)
	`is_booted` ()
	`load` (cancellable)
	`load_if_changed` (cancellable)
	`lock` ()
	`lock_async` (cancellable, callback, *user_data)
	`lock_finish` (result)
	`origin_new_from_refspec` (refspec)
	`prepare_cleanup` (cancellable)
	`query_deployments_for` (osname)
	`repo` ()
	`require_booted_deployment` ()
	`set_mount_namespace_in_use` ()
	`simple_write_deployment` (osname, new_deployment, merge_deployment, flags, cancellable)
	`stage_overlay_initrd` (fd, cancellable)
	`stage_tree` (osname, revision, origin, merge_deployment, override_kernel_argv, cancellable)
	`stage_tree_with_options` (osname, revision, origin, merge_deployment, opts, cancellable)
	`try_lock` ()
	`unload` ()
	`unlock` ()
	`update_post_copy` (cancellable)
	`write_deployments` (new_deployments, cancellable)
	`write_deployments_with_options` (new_deployments, opts, cancellable)
	`write_origin_file` (deployment, new_origin, cancellable)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`path`	`Gio.File`	r/w/co

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`journal-msg`	libostree will log to the journal various events, such as the /etc merge status, and transaction completion.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class OSTree.Sysroot(**kwargs)¶

Bases:: GObject.Object
Abstract:: No

classmethod get_deployment_origin_path(deployment_path)¶

Parameters:: deployment_path (Gio.File) – A deployment path
Returns:: Path to deployment origin file
Return type:: Gio.File

classmethod new(path)¶

Parameters:: path (Gio.File or None) – Path to a system root directory, or None to use the current visible root file system
Returns:: An accessor object for an system root located at path
Return type:: OSTree.Sysroot

Create a new OSTree.Sysroot object for the sysroot at path. If path is None, the current visible root file system is used, equivalent to OSTree.Sysroot.new_default().

classmethod new_default()¶

Returns:: An accessor for the current visible root / filesystem
Return type:: OSTree.Sysroot

change_finalization(deployment)¶

Parameters:: deployment (OSTree.Deployment) – Deployment which must be staged
Raises:: GLib.Error
Return type:: bool

Given the target deployment (which must be the staged deployment) this API will toggle its “finalization locking” state. If it is currently locked, it will be unlocked (and hence queued to apply on shutdown).

New in version 2023.8.

cleanup(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – Cancellable
Raises:: GLib.Error
Return type:: bool

Delete any state that resulted from a partially completed transaction, such as incomplete deployments.

cleanup_prune_repo(options, cancellable)¶

Parameters:

options (OSTree.RepoPruneOptions) – Flags controlling pruning
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Returns:

out_objects_total:: Number of objects found
out_objects_pruned:: Number of objects deleted
out_pruned_object_size_total:: Storage size in bytes of objects deleted

Return type:

(bool, out_objects_total: int, out_objects_pruned: int, out_pruned_object_size_total: int)

Prune the system repository. This is a thin wrapper around OSTree.Repo.prune_from_reachable(); the primary addition is that this function automatically gathers all deployed commits into the reachable set.

You generally want to at least set the OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY flag in options. A commit traversal depth of 0 is assumed.

Locking: exclusive

New in version 2018.6.

deploy_tree(osname, revision, origin, provided_merge_deployment, override_kernel_argv, cancellable)¶

Parameters:

osname (str or None) – osname to use for merge deployment
revision (str) – Checksum to add
origin (GLib.KeyFile or None) – Origin to use for upgrades
provided_merge_deployment (OSTree.Deployment or None) – Use this deployment for merge path
override_kernel_argv ([str] or None) – Use these as kernel arguments; if None, inherit options from provided_merge_deployment
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Returns:

out_new_deployment:: The new deployment path

Return type:

(bool, out_new_deployment: OSTree.Deployment)

Older version of OSTree.Sysroot.stage_tree_with_options().

New in version 2018.5.

deploy_tree_with_options(osname, revision, origin, provided_merge_deployment, opts, cancellable)¶

Parameters:

osname (str or None) – osname to use for merge deployment
revision (str) – Checksum to add
origin (GLib.KeyFile or None) – Origin to use for upgrades
provided_merge_deployment (OSTree.Deployment or None) – Use this deployment for merge path
opts (OSTree.SysrootDeployTreeOpts or None) – Options
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Returns:

out_new_deployment:: The new deployment path

Return type:

(bool, out_new_deployment: OSTree.Deployment)

Check out deployment tree with revision revision, performing a 3 way merge with provided_merge_deployment for configuration.

When booted into the sysroot, you should use the OSTree.Sysroot.stage_tree() API instead.

New in version 2020.7.

deployment_set_kargs(deployment, new_kargs, cancellable)¶

Parameters:

deployment (OSTree.Deployment) – A deployment
new_kargs ([str]) – Replace deployment’s kernel arguments
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

Entirely replace the kernel arguments of deployment with the values in new_kargs.

deployment_set_kargs_in_place(deployment, kargs_str, cancellable)¶

Parameters:

deployment (OSTree.Deployment) – A deployment
kargs_str (str or None) – Replace deployment's kernel arguments
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

Replace the kernel arguments of deployment with the values in kargs_str.

deployment_set_mutable(deployment, is_mutable, cancellable)¶

Parameters:

deployment (OSTree.Deployment) – A deployment
is_mutable (bool) – Whether or not deployment’s files can be changed
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

By default, deployment directories are not mutable. This function will allow making them temporarily mutable, for example to allow layering additional non-OSTree content.

deployment_set_pinned(deployment, is_pinned)¶

Parameters:

deployment (OSTree.Deployment) – A deployment
is_pinned (bool) – Whether or not deployment will be automatically GC’d

Raises:

GLib.Error

Return type:

bool

By default, deployments may be subject to garbage collection. Typical uses of libostree only retain at most 2 deployments. If is_pinned is TRUE, a metadata bit will be set causing libostree to avoid automatic GC of the deployment. However, this is really an “advisory” note; it’s still possible for e.g. older versions of libostree unaware of pinning to GC the deployment.

This function does nothing and returns successfully if the deployment is already in the desired pinning state. It is an error to try to pin the staged deployment (as it’s not in the bootloader entries).

New in version 2018.3.

deployment_unlock(deployment, unlocked_state, cancellable)¶

Parameters:

deployment (OSTree.Deployment) – Deployment
unlocked_state (OSTree.DeploymentUnlockedState) – Transition to this unlocked state
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

Configure the target deployment deployment such that it is writable. There are multiple modes, essentially differing in whether or not any changes persist across reboot.

The OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX state is persistent across reboots.

New in version 2016.4.

ensure_initialized(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – Cancellable
Raises:: GLib.Error
Return type:: bool

Ensure that self is set up as a valid rootfs, by creating /ostree/repo, among other things.

get_booted_deployment()¶

Returns:: The currently booted deployment, or None if none
Return type:: OSTree.Deployment or None

This function may only be called if the sysroot is loaded.

get_bootversion()¶

Return type:: int

get_deployment_directory(deployment)¶

Parameters:: deployment (OSTree.Deployment) – A deployment
Returns:: Path to deployment root directory
Return type:: Gio.File

get_deployment_dirpath(deployment)¶

Parameters:: deployment (OSTree.Deployment) – A deployment
Returns:: Path to deployment root directory, relative to sysroot
Return type:: str

Note this function only returns a *relative* path - if you want to access, it, you must either use fd-relative api such as openat(), or concatenate it with the full OSTree.Sysroot.get_path().

get_deployments()¶

Returns:: Ordered list of deployments
Return type:: [OSTree.Deployment]

get_fd()¶

Returns:: A file descriptor valid for the lifetime of self
Return type:: int

Access a file descriptor that refers to the root directory of this sysroot. OSTree.Sysroot.initialize() (or OSTree.Sysroot.load()) must have been invoked prior to calling this function.

get_merge_deployment(osname)¶

Parameters:: osname (str or None) – Operating system group
Returns:: Configuration merge deployment
Return type:: OSTree.Deployment or None

Find the deployment to use as a configuration merge source; this is the first one in the current deployment list which matches osname.

get_path()¶

Returns:: Path to rootfs
Return type:: Gio.File

get_repo(cancellable)¶

Parameters:

cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Returns:

True on success, False otherwise

out_repo:: Repository in sysroot self

Return type:

(bool, out_repo: OSTree.Repo)

Retrieve the OSTree repository in sysroot self. The repo is guaranteed to be open (see OSTree.Repo.open()).

get_staged_deployment()¶

Returns:: The currently staged deployment, or None if none
Return type:: OSTree.Deployment or None

New in version 2018.5.

get_subbootversion()¶

Return type:: int

init_osname(osname, cancellable)¶

Parameters:

osname (str) – Name group of operating system checkouts
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

Initialize the directory structure for an “osname”, which is a group of operating system deployments, with a shared /var. One is required for generating a deployment.

New in version 2016.4.

initialize()¶

Raises:: GLib.Error
Return type:: bool

Subset of OSTree.Sysroot.load(); performs basic initialization. Notably, one can invoke ostree_sysroot_get_fd() after calling this function.

It is not necessary to call this function if OSTree.Sysroot.load() is invoked.

New in version 2020.1.

initialize_with_mount_namespace(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) –
Raises:: GLib.Error
Return type:: bool

Prepare the current process for modifying a booted sysroot, if applicable. This function subsumes the functionality of ostree_sysroot_initialize and may be invoked wherever that function is.

If the sysroot does not appear to be booted, or where the current process is not uid 0, this function returns successfully.

Otherwise, if the process is in the same mount namespace as pid 1, create a new namespace.

If you invoke this function, it must be before OSTree.Sysroot.load(); it may be invoked before or after OSTree.Sysroot.initialize().

New in version 2022.7.

is_booted()¶

Returns:: True iff the sysroot points to a booted deployment
Return type:: bool

Can only be invoked after ostree_sysroot_initialize().

New in version 2020.1.

load(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – Cancellable
Raises:: GLib.Error
Return type:: bool

Load deployment list, bootversion, and subbootversion from the rootfs self.

load_if_changed(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – Cancellable
Raises:: GLib.Error
Return type:: (bool, out_changed: bool)

New in version 2016.4.

lock()¶

Raises:: GLib.Error
Return type:: bool

Acquire an exclusive multi-process write lock for self. This call blocks until the lock has been acquired. The lock is not reentrant.

Release the lock with OSTree.Sysroot.unlock(). The lock will also be released if self is deallocated.

lock_async(cancellable, callback, *user_data)¶

Parameters:

cancellable (Gio.Cancellable or None) – Cancellable
callback (Gio.AsyncReadyCallback or None) – Callback
user_data (object or None) – User data

An asynchronous version of OSTree.Sysroot.lock().

lock_finish(result)¶

Parameters:: result (Gio.AsyncResult) – Result
Raises:: GLib.Error
Return type:: bool

Call when OSTree.Sysroot.lock_async() is ready.

origin_new_from_refspec(refspec)¶

Parameters:: refspec (str) – A refspec
Returns:: A new config file which sets refspec as an origin
Return type:: GLib.KeyFile

prepare_cleanup(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – Cancellable
Raises:: GLib.Error
Return type:: bool

Like OSTree.Sysroot.cleanup() in that it cleans up incomplete deployments and old boot versions, but does NOT prune the repository.

query_deployments_for(osname)¶

Parameters:

osname (str or None) – “stateroot” name

Returns:

out_pending:: The pending deployment
out_rollback:: The rollback deployment

Return type:

(out_pending: OSTree.Deployment or None, out_rollback: OSTree.Deployment or None)

Find the pending and rollback deployments for osname. Pass None for osname to use the booted deployment’s osname. By default, pending deployment is the first deployment in the order that matches osname, and rollback will be the next one after the booted deployment, or the deployment after the pending if we’re not looking at the booted deployment.

New in version 2017.7.

repo()¶

Returns:: The OSTree repository in sysroot self.
Return type:: OSTree.Repo

This function is a variant of OSTree.Sysroot.get_repo() that cannot fail, and returns a cached repository. Can only be called after OSTree.Sysroot.initialize() or OSTree.Sysroot.load() has been invoked successfully.

New in version 2017.7.

require_booted_deployment()¶

Raises:: GLib.Error
Returns:: The currently booted deployment, or an error
Return type:: OSTree.Deployment

Find the booted deployment, or return an error if not booted via OSTree.

New in version 2021.1.

set_mount_namespace_in_use()¶

If this function is invoked, then libostree will assume that a private Linux mount namespace has been created by the process. The primary use case for this is to have e.g. /sysroot mounted read-only by default.

If this function has been called, then when a function which requires writable access is invoked, libostree will automatically remount as writable any mount points on which it operates. This currently is just /sysroot and /boot.

If you invoke this function, it must be before OSTree.Sysroot.load(); it may be invoked before or after OSTree.Sysroot.initialize().

New in version 2020.1.

simple_write_deployment(osname, new_deployment, merge_deployment, flags, cancellable)¶

Parameters:

osname (str or None) – OS name
new_deployment (OSTree.Deployment) – Prepend this deployment to the list
merge_deployment (OSTree.Deployment or None) – Use this deployment for configuration merge
flags (OSTree.SysrootSimpleWriteDeploymentFlags) – Flags controlling behavior
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

Prepend new_deployment to the list of deployments, commit, and cleanup. By default, all other deployments for the given osname except the merge deployment and the booted deployment will be garbage collected.

If OSTree.SysrootSimpleWriteDeploymentFlags.RETAIN is specified, then all current deployments will be kept.

If OSTree.SysrootSimpleWriteDeploymentFlags.RETAIN_PENDING is specified, then pending deployments will be kept.

If OSTree.SysrootSimpleWriteDeploymentFlags.RETAIN_ROLLBACK is specified, then rollback deployments will be kept.

If OSTree.SysrootSimpleWriteDeploymentFlags.NOT_DEFAULT is specified, then instead of prepending, the new deployment will be added right after the booted or merge deployment, instead of first.

If OSTree.SysrootSimpleWriteDeploymentFlags.NO_CLEAN is specified, then no cleanup will be performed after adding the deployment. Make sure to call OSTree.Sysroot.cleanup() sometime later, instead.

stage_overlay_initrd(fd, cancellable)¶

Parameters:

fd (int) – File descriptor to overlay initrd
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Returns:

out_checksum:: Overlay initrd checksum

Return type:

(bool, out_checksum: str)

Stage an overlay initrd to be used in an upcoming deployment. Returns a checksum which can be passed to OSTree.Sysroot.deploy_tree_with_options() or OSTree.Sysroot.stage_tree_with_options() via the overlay_initrds array option.

New in version 2020.7.

stage_tree(osname, revision, origin, merge_deployment, override_kernel_argv, cancellable)¶

Parameters:

osname (str or None) – osname to use for merge deployment
revision (str) – Checksum to add
origin (GLib.KeyFile or None) – Origin to use for upgrades
merge_deployment (OSTree.Deployment or None) – Use this deployment for merge path
override_kernel_argv ([str] or None) – Use these as kernel arguments; if None, inherit options from provided_merge_deployment
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Returns:

out_new_deployment:: The new deployment path

Return type:

(bool, out_new_deployment: OSTree.Deployment)

Older version of OSTree.Sysroot.stage_tree_with_options().

New in version 2018.5.

stage_tree_with_options(osname, revision, origin, merge_deployment, opts, cancellable)¶

Parameters:

osname (str or None) – osname to use for merge deployment
revision (str) – Checksum to add
origin (GLib.KeyFile or None) – Origin to use for upgrades
merge_deployment (OSTree.Deployment or None) – Use this deployment for merge path
opts (OSTree.SysrootDeployTreeOpts) – Options
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Returns:

out_new_deployment:: The new deployment path

Return type:

(bool, out_new_deployment: OSTree.Deployment)

Like OSTree.Sysroot.deploy_tree(), but “finalization” only occurs at OS shutdown time.

New in version 2020.7.

try_lock()¶

Raises:

GLib.Error

Returns:

out_acquired:: Whether or not the lock has been acquired

Return type:

(bool, out_acquired: bool)

Try to acquire an exclusive multi-process write lock for self. If another process holds the lock, this function will return immediately, setting out_acquired to False, and returning True (and no error).

Release the lock with OSTree.Sysroot.unlock(). The lock will also be released if self is deallocated.

unload()¶

Release any resources such as file descriptors referring to the root directory of this sysroot. Normally, those resources are cleared by finalization, but in garbage collected languages that may not be predictable.

This undoes the effect of ostree_sysroot_load().

unlock()¶: Clear the lock previously acquired with OSTree.Sysroot.lock(). It is safe to call this function if the lock has not been previously acquired.

update_post_copy(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) –
Raises:: GLib.Error
Return type:: bool

Update a sysroot as needed after having copied it into place using file-level operations. This enables options like fs-verity on the required files that may have been lost during the copy.

New in version 2023.11.

write_deployments(new_deployments, cancellable)¶

Parameters:

new_deployments ([OSTree.Deployment]) – List of new deployments
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

Older version of OSTree.Sysroot.write_deployments_with_options(). This version will perform post-deployment cleanup by default.

write_deployments_with_options(new_deployments, opts, cancellable)¶

Parameters:

new_deployments ([OSTree.Deployment]) – List of new deployments
opts (OSTree.SysrootWriteDeploymentsOpts) – Options
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

Assuming new_deployments have already been deployed in place on disk via OSTree.Sysroot.deploy_tree(), atomically update bootloader configuration. By default, no post-transaction cleanup will be performed. You should invoke OSTree.Sysroot.cleanup() at some point after the transaction, or specify do_postclean in opts. Skipping the post-transaction cleanup is useful if for example you want to control pruning of the repository.

New in version 2017.4.

write_origin_file(deployment, new_origin, cancellable)¶

Parameters:

deployment (OSTree.Deployment) – Deployment
new_origin (GLib.KeyFile or None) – Origin content
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

GLib.Error

Return type:

bool

Immediately replace the origin file of the referenced deployment with the contents of new_origin. If new_origin is None, this function will write the current origin of deployment.

Signal Details¶

OSTree.Sysroot.signals.journal_msg(sysroot, msg)¶

Signal Name:

journal-msg

Flags:

RUN_LAST

Parameters:

sysroot (OSTree.Sysroot) – The object which received the signal
msg (str) – Human-readable string (should not contain newlines)

libostree will log to the journal various events, such as the /etc merge status, and transaction completion. Connect to this signal to also synchronously receive the text for those messages. This is intended to be used by command line tools which link to libostree as a library.

Currently, the structured data is only available via the systemd journal.

New in version 2017.10.

Property Details¶

OSTree.Sysroot.props.path¶

Name:: path
Type:: Gio.File
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY