ostree_sysroot_new ()

OstreeSysroot *
ostree_sysroot_new (GFile *path);

Create a new OstreeSysroot object for the sysroot at path . If path is NULL, the current visible root file system is used, equivalent to ostree_sysroot_new_default().

ostree_sysroot_new_default ()

OstreeSysroot *
ostree_sysroot_new_default (void);

ostree_sysroot_initialize ()

gboolean
ostree_sysroot_initialize (OstreeSysroot *self,
                           GError **error);

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.

Since: 2020.1

ostree_sysroot_initialize_with_mount_namespace ()

gboolean
ostree_sysroot_initialize_with_mount_namespace
                               (OstreeSysroot *self,
                                GCancellable *cancellable,
                                GError **error);

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().

Since: 2022.7

ostree_sysroot_get_path ()

GFile *
ostree_sysroot_get_path (OstreeSysroot *self);

ostree_sysroot_load ()

gboolean
ostree_sysroot_load (OstreeSysroot *self,
                     GCancellable *cancellable,
                     GError **error);

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

ostree_sysroot_load_if_changed ()

gboolean
ostree_sysroot_load_if_changed (OstreeSysroot *self,
                                gboolean *out_changed,
                                GCancellable *cancellable,
                                GError **error);

Since: 2016.4

ostree_sysroot_lock ()

gboolean
ostree_sysroot_lock (OstreeSysroot *self,
                     GError **error);

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.

ostree_sysroot_try_lock ()

gboolean
ostree_sysroot_try_lock (OstreeSysroot *self,
                         gboolean *out_acquired,
                         GError **error);

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.

ostree_sysroot_lock_async ()

void
ostree_sysroot_lock_async (OstreeSysroot *self,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

An asynchronous version of ostree_sysroot_lock().

ostree_sysroot_lock_finish ()

gboolean
ostree_sysroot_lock_finish (OstreeSysroot *self,
                            GAsyncResult *result,
                            GError **error);

Call when ostree_sysroot_lock_async() is ready.

ostree_sysroot_unlock ()

void
ostree_sysroot_unlock (OstreeSysroot *self);

Clear the lock previously acquired with ostree_sysroot_lock(). It is safe to call this function if the lock has not been previously acquired.

ostree_sysroot_unload ()

void
ostree_sysroot_unload (OstreeSysroot *self);

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().

ostree_sysroot_update_post_copy ()

gboolean
ostree_sysroot_update_post_copy (OstreeSysroot *self,
                                 GCancellable *cancellable,
                                 GError **error);

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.

Since: 2023.11

ostree_sysroot_set_mount_namespace_in_use ()

void
ostree_sysroot_set_mount_namespace_in_use
                               (OstreeSysroot *self);

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().

Since: 2020.1

ostree_sysroot_is_booted ()

gboolean
ostree_sysroot_is_booted (OstreeSysroot *self);

Can only be invoked after ostree_sysroot_initialize().

Since: 2020.1

ostree_sysroot_get_fd ()

int
ostree_sysroot_get_fd (OstreeSysroot *self);

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.

ostree_sysroot_ensure_initialized ()

gboolean
ostree_sysroot_ensure_initialized (OstreeSysroot *self,
                                   GCancellable *cancellable,
                                   GError **error);

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

ostree_sysroot_get_bootversion ()

int
ostree_sysroot_get_bootversion (OstreeSysroot *self);

ostree_sysroot_get_subbootversion ()

int
ostree_sysroot_get_subbootversion (OstreeSysroot *self);

ostree_sysroot_get_deployments ()

GPtrArray *
ostree_sysroot_get_deployments (OstreeSysroot *self);

ostree_sysroot_get_booted_deployment ()

OstreeDeployment *
ostree_sysroot_get_booted_deployment (OstreeSysroot *self);

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

ostree_sysroot_require_booted_deployment ()

OstreeDeployment *
ostree_sysroot_require_booted_deployment
                               (OstreeSysroot *self,
                                GError **error);

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

Since: 2021.1

ostree_sysroot_get_deployment_directory ()

GFile *
ostree_sysroot_get_deployment_directory
                               (OstreeSysroot *self,
                                OstreeDeployment *deployment);

ostree_sysroot_get_deployment_dirpath ()

char *
ostree_sysroot_get_deployment_dirpath (OstreeSysroot *self,
                                       OstreeDeployment *deployment);

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().

ostree_sysroot_get_deployment_origin_path ()

GFile *
ostree_sysroot_get_deployment_origin_path
                               (GFile *deployment_path);

ostree_sysroot_cleanup ()

gboolean
ostree_sysroot_cleanup (OstreeSysroot *self,
                        GCancellable *cancellable,
                        GError **error);

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

ostree_sysroot_prepare_cleanup ()

gboolean
ostree_sysroot_prepare_cleanup (OstreeSysroot *self,
                                GCancellable *cancellable,
                                GError **error);

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

ostree_sysroot_cleanup_prune_repo ()

gboolean
ostree_sysroot_cleanup_prune_repo (OstreeSysroot *sysroot,
                                   OstreeRepoPruneOptions *options,
                                   gint *out_objects_total,
                                   gint *out_objects_pruned,
                                   guint64 *out_pruned_object_size_total,
                                   GCancellable *cancellable,
                                   GError **error);

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

Since: 2018.6

ostree_sysroot_repo ()

OstreeRepo *
ostree_sysroot_repo (OstreeSysroot *self);

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.

Since: 2017.7

ostree_sysroot_get_repo ()

gboolean
ostree_sysroot_get_repo (OstreeSysroot *self,
                         OstreeRepo **out_repo,
                         GCancellable *cancellable,
                         GError **error);

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

ostree_sysroot_get_staged_deployment ()

OstreeDeployment *
ostree_sysroot_get_staged_deployment (OstreeSysroot *self);

Since: 2018.5

ostree_sysroot_init_osname ()

gboolean
ostree_sysroot_init_osname (OstreeSysroot *self,
                            const char *osname,
                            GCancellable *cancellable,
                            GError **error);

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.

Since: 2016.4

ostree_sysroot_deployment_set_kargs ()

gboolean
ostree_sysroot_deployment_set_kargs (OstreeSysroot *self,
                                     OstreeDeployment *deployment,
                                     char **new_kargs,
                                     GCancellable *cancellable,
                                     GError **error);

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

ostree_sysroot_deployment_set_kargs_in_place ()

gboolean
ostree_sysroot_deployment_set_kargs_in_place
                               (OstreeSysroot *self,
                                OstreeDeployment *deployment,
                                char *kargs_str,
                                GCancellable *cancellable,
                                GError **error);

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

ostree_sysroot_deployment_set_mutable ()

gboolean
ostree_sysroot_deployment_set_mutable (OstreeSysroot *self,
                                       OstreeDeployment *deployment,
                                       gboolean is_mutable,
                                       GCancellable *cancellable,
                                       GError **error);

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

ostree_sysroot_deployment_unlock ()

gboolean
ostree_sysroot_deployment_unlock (OstreeSysroot *self,
                                  OstreeDeployment *deployment,
                                  OstreeDeploymentUnlockedState unlocked_state,
                                  GCancellable *cancellable,
                                  GError **error);

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.

Since: 2016.4

ostree_sysroot_deployment_set_pinned ()

gboolean
ostree_sysroot_deployment_set_pinned (OstreeSysroot *self,
                                      OstreeDeployment *deployment,
                                      gboolean is_pinned,
                                      GError **error);

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).

Since: 2018.3

ostree_sysroot_write_deployments ()

gboolean
ostree_sysroot_write_deployments (OstreeSysroot *self,
                                  GPtrArray *new_deployments,
                                  GCancellable *cancellable,
                                  GError **error);

Older version of ostree_sysroot_write_deployments_with_options(). This version will perform post-deployment cleanup by default.

ostree_sysroot_write_deployments_with_options ()

gboolean
ostree_sysroot_write_deployments_with_options
                               (OstreeSysroot *self,
                                GPtrArray *new_deployments,
                                OstreeSysrootWriteDeploymentsOpts *opts,
                                GCancellable *cancellable,
                                GError **error);

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.

Since: 2017.4

ostree_sysroot_write_origin_file ()

gboolean
ostree_sysroot_write_origin_file (OstreeSysroot *sysroot,
                                  OstreeDeployment *deployment,
                                  GKeyFile *new_origin,
                                  GCancellable *cancellable,
                                  GError **error);

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

ostree_sysroot_stage_tree ()

gboolean
ostree_sysroot_stage_tree (OstreeSysroot *self,
                           const char *osname,
                           const char *revision,
                           GKeyFile *origin,
                           OstreeDeployment *merge_deployment,
                           char **override_kernel_argv,
                           OstreeDeployment **out_new_deployment,
                           GCancellable *cancellable,
                           GError **error);

Older version of ostree_sysroot_stage_tree_with_options().

Since: 2018.5

ostree_sysroot_stage_tree_with_options ()

gboolean
ostree_sysroot_stage_tree_with_options
                               (OstreeSysroot *self,
                                const char *osname,
                                const char *revision,
                                GKeyFile *origin,
                                OstreeDeployment *merge_deployment,
                                OstreeSysrootDeployTreeOpts *opts,
                                OstreeDeployment **out_new_deployment,
                                GCancellable *cancellable,
                                GError **error);

Like ostree_sysroot_deploy_tree(), but "finalization" only occurs at OS shutdown time.

Since: 2020.7

ostree_sysroot_stage_overlay_initrd ()

gboolean
ostree_sysroot_stage_overlay_initrd (OstreeSysroot *self,
                                     int fd,
                                     char **out_checksum,
                                     GCancellable *cancellable,
                                     GError **error);

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.

Since: 2020.7

ostree_sysroot_change_finalization ()

gboolean
ostree_sysroot_change_finalization (OstreeSysroot *self,
                                    OstreeDeployment *deployment,
                                    GError **error);

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).

Since: 2023.8

ostree_sysroot_deploy_tree ()

gboolean
ostree_sysroot_deploy_tree (OstreeSysroot *self,
                            const char *osname,
                            const char *revision,
                            GKeyFile *origin,
                            OstreeDeployment *provided_merge_deployment,
                            char **override_kernel_argv,
                            OstreeDeployment **out_new_deployment,
                            GCancellable *cancellable,
                            GError **error);

Older version of ostree_sysroot_stage_tree_with_options().

Since: 2018.5

ostree_sysroot_deploy_tree_with_options ()

gboolean
ostree_sysroot_deploy_tree_with_options
                               (OstreeSysroot *self,
                                const char *osname,
                                const char *revision,
                                GKeyFile *origin,
                                OstreeDeployment *provided_merge_deployment,
                                OstreeSysrootDeployTreeOpts *opts,
                                OstreeDeployment **out_new_deployment,
                                GCancellable *cancellable,
                                GError **error);

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.

Since: 2020.7

ostree_sysroot_get_merge_deployment ()

OstreeDeployment *
ostree_sysroot_get_merge_deployment (OstreeSysroot *self,
                                     const char *osname);

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

ostree_sysroot_query_deployments_for ()

void
ostree_sysroot_query_deployments_for (OstreeSysroot *self,
                                      const char *osname,
                                      OstreeDeployment **out_pending,
                                      OstreeDeployment **out_rollback);

Find the pending and rollback deployments for osname . Pass NULL 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.

Since: 2017.7

ostree_sysroot_origin_new_from_refspec ()

GKeyFile *
ostree_sysroot_origin_new_from_refspec
                               (OstreeSysroot *self,
                                const char *refspec);

ostree_sysroot_simple_write_deployment ()

gboolean
ostree_sysroot_simple_write_deployment
                               (OstreeSysroot *sysroot,
                                const char *osname,
                                OstreeDeployment *new_deployment,
                                OstreeDeployment *merge_deployment,
                                OstreeSysrootSimpleWriteDeploymentFlags flags,
                                GCancellable *cancellable,
                                GError **error);

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_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN is specified, then all current deployments will be kept.

If OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING is specified, then pending deployments will be kept.

If OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK is specified, then rollback deployments will be kept.

If OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_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_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN is specified, then no cleanup will be performed after adding the deployment. Make sure to call ostree_sysroot_cleanup() sometime later, instead.

OstreeSysroot

typedef struct OstreeSysroot OstreeSysroot;

enum OstreeSysrootSimpleWriteDeploymentFlags