diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000000..e69de29bb2 diff --git a/CONTRIBUTING/index.html b/CONTRIBUTING/index.html new file mode 100644 index 0000000000..83a6678fe7 --- /dev/null +++ b/CONTRIBUTING/index.html @@ -0,0 +1,462 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Contributing | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Contributing + + +

+ + +
    +
  1. Submitting patches
  2. +
  3. Commit message style
  4. +
  5. Running the test suite
  6. +
  7. Coding style
  8. +
  9. Contributing Tutorial
  10. +
  11. Release process
  12. +
+ + +

+ + + Submitting patches + + +

+ + +

A majority of current maintainers prefer the GitHub pull request +model, and this motivated moving the primary git repository to +https://github.com/ostreedev/ostree.

+ +

However, we do not use the “Merge pull request” button, because we do +not like merge commits for one-patch pull requests, among other +reasons. See this issue +for more information. Instead, we use an instance of +Homu, currently known as +cgwalters-bot.

+ +

As a review proceeds, the preferred method is to push fixup! commits. Any commits committed with the --fixup option will have have the word fixup! in its commit title. This is to indicate that this particular commit will be squashed with the commit that was specified in this command, git commit --fixup <commit ref or hash>. Homu knows how to use --autosquash when performing the final merge.

+ +

See the +Git documentation for more +information.

+ +

Alternative methods if you don’t like GitHub (also fully supported):

+ +
    +
  1. Send mail to ostree-list@gnome.org, with the patch attached
  2. +
  3. Attach them to https://bugzilla.gnome.org/
  4. +
+ +

It is likely however once a patch is ready to apply a maintainer +will push it to a GitHub PR, and merge via Homu.

+

+ + + Commit message style + + +

+ + +

Please look at git log and match the commit log style, which is very +similar to the +Linux kernel.

+ +

You may use Signed-off-by, but we’re not requiring it.

+ +

General Commit Message Guidelines:

+ +
    +
  1. Title +
      +
    • Specify the context or category of the changes e.g. lib for library changes, docs for document changes, bin/<command-name> for command changes, etc.
    • +
    • Begin the title with the first letter of the first word capitalized.
    • +
    • Aim for less than 50 characters, otherwise 72 characters max.
    • +
    • Do not end the title with a period.
    • +
    • Use an imperative tone.
    • +
    +
  2. +
  3. Body +
      +
    • Separate the body with a blank line after the title.
    • +
    • Begin a paragraph with the first letter of the first word capitalized.
    • +
    • Each paragraph should be formatted within 72 characters.
    • +
    • Content should be about what was changed and why this change was made.
    • +
    • If your commit fixes an issue, the commit message should end with Closes: #<number>.
    • +
    +
  4. +
+ +

Commit Message example:

+ +
<context>: Less than 50 characters for subject title
+
+A paragraph of the body should be within 72 characters.
+
+This paragraph is also less than 72 characters.
+
+ +

For more information see How to Write a Git Commit Message

+ +

Editing a Committed Message:

+ +

To edit the message from the most recent commit run git commit --amend. To change older commits on the branch use git rebase -i. For a successful rebase have the branch track upstream main. Once the changes have been made and saved, run git push --force origin <branch-name>.

+

+ + + Running the test suite + + +

+ + +

OSTree uses both make check and supports the +Installed Tests +model as well (if --enable-installed-tests is provided).

+

+ + + Coding style + + +

+ + +

Indentation is GNU. Files should start with the appropriate mode lines.

+ +

Use GCC __attribute__((cleanup)) wherever possible. If interacting +with a third party library, try defining local cleanup macros.

+ +

Use GError and GCancellable where appropriate.

+ +

Prefer returning gboolean to signal success/failure, and have output +values as parameters.

+ +

Prefer linear control flow inside functions (aside from standard +loops). In other words, avoid “early exits” or use of goto besides +goto out;.

+ +

This is an example of an “early exit”:

+ +
static gboolean
+myfunc (...)
+{
+    gboolean ret = FALSE;
+
+    /* some code */
+
+    /* some more code */
+
+    if (condition)
+      return FALSE;
+
+    /* some more code */
+
+    ret = TRUE;
+  out:
+    return ret;
+}
+
+ +

If you must shortcut, use:

+ +
if (condition)
+  {
+    ret = TRUE;
+    goto out;
+  }
+
+ +

A consequence of this restriction is that you are encouraged to avoid +deep nesting of loops or conditionals. Create internal static helper +functions, particularly inside loops. For example, rather than:

+ +
while (condition)
+  {
+    /* some code */
+    if (condition)
+      {
+         for (i = 0; i < somevalue; i++)
+           {
+              if (condition)
+                {
+                  /* deeply nested code */
+                }
+
+                /* more nested code */
+           }
+      }
+  }
+
+ +

Instead do this:

+ +
static gboolean
+helperfunc (..., GError **error)
+{
+  if (condition)
+   {
+     /* deeply nested code */
+   }
+
+  /* more nested code */
+
+  return ret;
+}
+
+while (condition)
+  {
+    /* some code */
+    if (!condition)
+      continue;
+
+    for (i = 0; i < somevalue; i++)
+      {
+        if (!helperfunc (..., i, error))
+          goto out;
+      }
+  }
+
+

+ + + Contributing Tutorial + + +

+ + +

For a detailed walk-through on building, modifying, and testing, see this tutorial on how to start contributing to OSTree.

+

+ + + Release process + + +

+ + +

Releases can be performed by creating a new release ticket and following the steps in the checklist there.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/README-historical/index.html b/README-historical/index.html new file mode 100644 index 0000000000..6337e9ad35 --- /dev/null +++ b/README-historical/index.html @@ -0,0 +1,781 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Historical OSTree README | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Historical OSTree README + + +

+ + + + +

This file is outdated, but some of the text here is still useful for +historical context. I’m preserving it (explicitly still in the tree) +for posterity.

+

+ + + Problem statement + + +

+ + +

Hacking on the core operating system is painful - this includes most +of GNOME from upower and NetworkManager up to gnome-shell. I want a +system that matches these requirements:

+ +
    +
  1. Does not disturb your existing OS
  2. +
  3. Is not terribly slow to use
  4. +
  5. Shares your $HOME - you have your data
  6. +
  7. Allows easy rollback
  8. +
  9. Ideally allows access to existing apps
  10. +
+

+ + + Comparison with existing tools + + +

+ + +
    +
  • +

    Virtualization

    + +

    Fails on points 2) and 3). Actually qemu-kvm can be pretty fast, + but in a lot of cases there is no substitute for actually booting + on bare metal; GNOME 3 really needs some hardware GPU + acceleration.

    +
  • +
  • +

    Rebuilding distribution packages

    + +

    Fails on points 1) and 4). Is also just very annoying: dpkg/rpm + both want tarballs, which you don’t have since you’re working from + git. The suggested “mock/pbuilder” type chroot builds are slow. + And even with non-chroot builds there is lots of pointless build + wrapping going on. Both dpkg and rpm also are poor at helping you + revert back to the original system.

    + +

    All of this can be scripted to be less bad of course - and I have + worked on such scripts. But fundamentally you’re still fighting + the system, and if you’re hacking on a lowlevel library like say + glib, you can easily get yourself to the point where you need a + recovery CD - at that point your edit/compile/debug cycle is just + too long.

    +
  • +
  • +

    “sudo make install”

    + +

    Now your system is in an undefined state. You can use e.g. rpm + -qV to try to find out what you overwrote, but neither dpkg nor + rpm will help clean up any files left over that aren’t shipped by + the old package.

    + +

    This is most realistic option for people hacking on system + components currently, but ostree will be better.

    +
  • +
  • +

    LXC / containers

    + +

    Fails on 3), and 4) is questionable. Also shares the annoying part +of rebuilding distribution packages. LXC is focused on running +multiple server systems at the same time, which isn’t what we +want (at least, not right now), and honestly even trying to support +that for a graphical desktop would be a lot of tricky work, for +example getting two GDM instances not to fight over VT +allocations. But some bits of the technology may make sense to use.

    +
  • +
  • +

    jhbuild + distribution packages

    + +

    The state of the art in GNOME - but can only build non-root things - + this means you can’t build NetworkManager, and thus are permanently + stuck on whatever the distro provides.

    +
  • +
+

+ + + Who is ostree for? + + +

+ + +

First - operating system developers and testers. I specifically keep +a few people in mind - Dan Williams and Eric Anholt, as well as myself +obviously. For Eric Anholt, a key use case for him is being able to +try out the latest gnome-shell, and combine it with his work on Mesa, +and see how it works/performs - while retaining the ability to roll +back if one or both breaks.

+ +

The rollback concept is absolutely key for shipping anything to +enthusiasts or knowledable testers. With a system like this, a tester +can easily perform a local rollback - something just not well +supported by dpkg/rpm. (What about Conary? See below.)

+ +

Also, distributing operating system trees (instead of packages) gives +us a sane place to perform automated QA before we ship it to +testers. We should never be wasting these people’s time.

+ +

Even better, this system would allow testers to bisect across +operating system builds, and do so very efficiently.

+

+ + + The core idea - chroots + + +

+ + +

chroots are the original lightweight “virtualization”. Let’s use +them. So basically, you install a mainstream distribution (say +Debian). It has a root filesystem like this:

+ +
	/usr
+	/etc
+	/home
+	...
+
+ +

Now, what we can do is have a system that installs chroots as a subdirectory +of the root, like:

+ +
	/ostree/gnomeos-3.0-opt-393a4555/{usr,etc,sbin,...}
+	/ostree/gnomeos-3.2-opt-7e9788a2/{usr,etc,sbin,...}
+
+ +

These live in the same root filesystem as your regular distribution +(Note though, the root partition should be reasonably sized, or +hopefully you’ve used just one big partition).

+ +

You should be able to boot into one of these roots. Since ostree +lives inside a distro created partition, a tricky part here is that we +need to know how to interact with the installed distribution’s grub. +This is an annoying but tractable problem.

+ +

First, we install a kernel+initramfs alongside the distribution’s. +Then, we have a “trampoline” ostree-init binary which is statically +linked, and boot the kernel with init=/ostree/ostree-init. This then +takes care of chrooting and running the init binary.

+ +

An important note here is that we bind mount the real /home. This +means you have your data. This also implies we share uid/gid, so +/etc/passwd will have to be in sync. Probably what we’ll do is have a +script to pull the data from the “host” OS.

+ +

I’ve decided for now to move /var into /ostree to avoid sharing it +with the “host” distribution, because in practice we’re likely +to hit incompatibilities.

+ +

Do note however /etc lives inside the OSTree; it’s presently +versioned and readonly like everything else.

+ +

On a pure OSTree system, the filesystem layout will look like this:

+ +
	.
+	|-- boot
+	|-- home
+	|-- ostree
+	|   |-- var
+	|   |-- current -> gnomeos-3.2-opt-7e9788a2
+	|   |-- gnomeos-3.0-opt-393a4555
+	|   |   |-- etc
+	|   |   |-- lib
+	|   |   |-- mnt
+	|   |   |-- proc
+	|   |   |-- run
+	|   |   |-- sbin
+	|   |   |-- srv
+	|   |   |-- sys
+	|   |   `-- usr
+	|   `-- gnomeos-3.2-opt-7e9788a2
+	|       |-- etc
+	|       |-- lib
+	|       |-- mnt
+	|       |-- proc
+	|       |-- run
+	|       |-- sbin
+	|       |-- srv
+	|       |-- sys
+	|       `-- usr
+	|-- root
+
+

+ + + Making this efficient + + +

+ + +

One of the first things you’ll probably ask is “but won’t that use a +lot of disk space”? Indeed, it will, if you just unpack a set of RPMs +or .debs into each root.

+ +

Besides chroots, there’s another old Unix idea we can take advantage +of - hard links. These allow sharing the underlying data of a file, +with the tradeoff that changing any one file will change all names +that point to it. This mutability means that we have to either:

+ +
    +
  1. Make sure everything touching the operating system breaks hard links +This is probably tractable over a long period of time, but if anything +has a bug, then it corrupts the file effectively.
  2. +
  3. Make the core OS read-only, with a well-defined mechanism for mutating +under the control of ostree.
  4. +
+ +

I chose 2.

+

+ + + A userspace content-addressed versioning filesystem + + +

+ + +

At its very core, that’s what ostree is. Just like git. If you +understand git, you know it’s not like other revision control systems. +git is effectively a specialized, userspace filesystem, and that is a +very powerful idea.

+ +

At the core of git is the idea of “content-addressed objects”. For +background on this, see http://book.git-scm.com/7_how_git_stores_objects.html

+ +

Why not just use git? Basically because git is designed mainly for +source trees - it goes to effort to be sure it’s compressing text for +example, under the assumption that you have a lot of text. Its +handling of binaries is very generic and unoptimized.

+ +

In contrast, ostree is explicitly designed for binaries, and in +particular one type of binary - ELF executables (or it will be once we +start using bsdiff).

+ +

Another big difference versus git is that ostree uses hard links +between “checkouts” and the repository. This means each checkout uses +almost no additional space, and is extremely fast to check out. We +can do this because again each checkout is designed to be read-only.

+ +

So we mentioned above there are:

+ +
	/ostree/gnomeos-3.2-opt-7e9788a2
+	/ostree/gnomeos-3.2-opt-393a4555
+
+ +

There is also a “repository” that looks like this:

+ +
	/ostree/repo/objects/17/a95e8ca0ba655b09cb68d7288342588e867ee0.file
+	/ostree/repo/objects/17/68625e7ff5a8db77904c77489dc6f07d4afdba.meta
+	/ostree/repo/objects/17/cc01589dd8540d85c0f93f52b708500dbaa5a9.file
+	/ostree/repo/objects/30
+	/ostree/repo/objects/30/6359b3ca7684358a3988afd005013f13c0c533.meta
+	/ostree/repo/objects/30/8f3c03010cedd930b1db756ce659c064f0cd7f.meta
+	/ostree/repo/objects/30/8cf0fd8e63dfff6a5f00ba5a48f3b92fb52de7.file
+	/ostree/repo/objects/30/6cad7f027d69a46bb376044434bbf28d63e88d.file
+
+ +

Each object is either metadata (like a commit or tree), or a hard link +to a regular file.

+ +

Note that also unlike git, the checksum here includes metadata such +as uid, gid, permissions, and extended attributes. (It does not include +file access times, since those shouldn’t matter for the OS)

+ +

This is another important component to allowing the hardlinks. We +wouldn’t want say all empty files to be shared necessarily. (Though +maybe this is wrong, and since the OS is readonly, we can make all +files owned by root without loss of generality).

+ +

However this tradeoff means that we probably need a second index by +content, so we don’t have to redownload the entire OS if permissions +change =)

+

+ + + Atomic upgrades, rollback + + +

+ + +

OSTree is designed to atomically swap operating systems - such that +during an upgrade and reboot process, you either get the full new +system, or the old one. There is no “Please don’t turn off your +computer”. We do this by simply using a symbolic link like:

+ +

/ostree/current -> /ostree/gnomeos-3.4-opt-e3b0c4429

+ +

Where gnomeos-e3b0c4429 has the full regular filesystem tree with usr/ +etc/ directories as above. To upgrade or rollback (there is no +difference internally), we simply check out a new tree into +gnomeos-b90ae4763 for example, then swap the “current” symbolic link, +then remove the old tree.

+ +

But does this mean you have to reboot for OS upgrades? Very likely, +yes - and this is no different from RPM/deb or whatever. They just +typically lie to you about it =)

+ +

A typical model with RPM/deb is to unpack the new files, then use some +IPC mechanism (SIGHUP, a control binary like /usr/sbin/apachectl) to +signal the running process to reload. There are multiple problems +with this - one is that in the new state, daemon A may depend on the +updated configuration in daemon B. This may not be particularly +common in default configurations, but it’s highly likely that that +some deployments will have e.g. apache talking to a local MySQL +instance. So you really want to do is only apply the updated +configuration when all the files are in place; not after each RPM or +.deb is installed.

+ +

What’s even harder is the massive set of race conditions that are +possible while RPM/deb are in the process of upgrading. Cron jobs are +very likely to hit this. If we want the ability to apply updates to a +live system, we could first pause execution of non-upgrade userspace +tasks. This could be done via SIGSTOP for example. Then, we can swap +around the filesystem tree, and then finally attempt to apply updates +via SIGHUP, and if possible, restart processes.

+

+ + + Configuration Management + + +

+ + +

By now if you’ve thought about this problem domain before, you’re wondering +about configuration management. In other words, if the OS is read only, +how do I edit /etc/sudoers?

+ +

Well, have you ever been a system administrator on a zypper/yum +system, done an RPM update, which then drops .rpmnew files in your +/etc/ that you have to go and hunt for with “find” or something, and +said to yourself, “Wow, this system is awesome!!!” ? Right, that’s +what I thought.

+ +

Configuration (and systems) management is a tricky problem, and I +certainly don’t have a magic bullet. However, one large conceptual +improvement I think is defaulting to “rebase” versus “merge”.

+ +

This means that we won’t permit direct modification of /etc - instead, +you HAVE to write a script which accomplishes your goals. To generate +a tree, we check out a new copy, then run your script on top.

+ +

If the script fails, we can roll back the update, or drop to a shell +if interactive.

+ +

However, we also need to consider cases where the administrator +modifies state indirectly by a program. Think “adduser” for example.

+ +

Possible approaches:

+ +
    +
  1. Patch all of these programs to know how to write to the writable +location, instead of the R/O bind mount overlay.
  2. +
  3. Move the data to /var
  4. +
+

+ + + What about “packages”? + + +

+ + +

There are several complex and separate issues hiding in this seemingly +simple question.

+ +

I think OSTree always makes sense to use as a core operating system +builder and updater. By “core” here I mean the parts that aren’t +removable. Debian has Essential: yes, any other distribution has this +too implicitly in the set of dependencies for their updater tool.

+ +

Now, let me just say I will absolutely support using something like +apt/yum/zypper (and consequently deb/rpm) on top of OSTree. This +isn’t trivial, but there aren’t any conceptual issues.

+ +

Concretely for example, RPM or .deb might make sense as a delivery +vehicle for third party OS extensions. A canoncial example is the +NVidia graphics driver.

+ +

If one is using OSTree to build an operating system, then there has +to be some API for applications. And that demands its own targeted +solution - something like an evolved glick (zeroinstall is also +similar).

+ +

Current package systems are totally broken for application deployment +though; for example, they will remove files away from under running +applications on update. And we clearly need the ability to install +and upgrade applications without rebooting the OS.

+

+ + + Details of RPM installation + + +

+ + +

We should be able to install LSB rpms. This implies providing “rpm”. +The tricky part here is since the OS itself is not assembled via RPMs, +we need to fake up a database of “provides” as if we were. Even +harder would be maintaining binary compatibilty with any arbitrary +%post scripts that may be run.

+

+ + + What about BTRFS? Doesn’t it solve everything? + + +

+ + +

In short, BTRFS is not a magic bullet, but yes - it helps +significantly. The obvious thing to do is layer BTRFS under dpkg/rpm, +and have a separate subvolume for /home so rollbacks don’t lose your +data. See e.g. +http://fedoraproject.org/wiki/Features/SystemRollbackWithBtrfs

+ +

As a general rule an issue with the BTRFS is that it can’t roll back +just changes to things installed by RPM (i.e. what’s in rpm -qal).

+ +

For example, it’s possible to e.g. run yum update, then edit something +in /etc, reboot and notice things are broken, then roll back and have +silently lost your changes to /etc.

+ +

Another example is adding a new binary in /usr/local. You could say, +“OK, we’ll use subvolumes for those!”. But then what about /var (and +your VM images that live in /var/lib/libvirt ?)

+ +

Finally, probably the biggest disadvantage of the rpm/dpkg + BTRFS +approach is it doesn’t solve the race conditions that happen when +unpacking packages into the live system. This problem is really +important to me.

+ +

Note though ostree can definitely take advantage of BTRFS features! +In particular, we could use “reflink” +http://lwn.net/Articles/331808/ instead of hard links, and avoid +having the object store corrupted if somehow the files are modified +directly.

+

+ + + Other systems + + +

+ + +

I’ve spent a long time thinking about this problem, and here are some +of the other possible solutions out there I looked at, and why I +didn’t use them:

+ +
    +
  • +

    Git: http://git-scm.com/

    + +

    Really awesome, and the core inspiration here. But like I mentioned + above, not at all designed for binaries - we can make different tradeoffs.

    +
  • +
  • +

    bup: https://github.com/apenwarr/bup

    + +

    bup is cool. But it shares the negative tradeoffs with git, though it + does add positives of its own. It also inspired me.

    +
  • +
  • +

    git-annex: http://git-annex.branchable.com/git-annex/

    + +

    Looks interesting; I think this will share the same negative tradeoffs with git +as far as using it for an OS goes.

    +
  • +
  • +

    schroot: http://www.debian-administration.org/articles/566

    + +

    Like LXC/containers, but just using a chroot.

    +
  • +
  • +

    NixOS: http://nixos.org/

    + +

    The NixOS people have a lot of really good ideas, and they’ve definitely + thought about the problem space. However, their approach of checksumming + all inputs to a package is pretty wacky. I don’t see the point, and moreover + it uses gobs of disk space.

    +
  • +
  • +

    Conary: http://wiki.rpath.com/wiki/Conary:Updates_and_Rollbacks

    + +

    If rpm/dpkg are like CVS, Conary is closer to Subversion. It’s not +bad, but ostree is better than it for the exact same reasons git +is better than Subversion.

    +
  • +
  • +

    BTRFS: http://en.wikipedia.org/wiki/Btrfs

    + +

    See above.

    +
  • +
  • +

    Solaris IPS: http://hub.opensolaris.org/bin/view/Project+pkg/

    + +

    Rollback is ZFS level, so I think this shares the same tradeoffs as BTRFS+RPM/deb. +They probably have some vertical integration though which definitely helps. +Obviously we can’t use ZFS.

    +
  • +
  • +

    Jhbuild: https://live.gnome.org/Jhbuild

    + +

    What we’ve been using in GNOME, and has the essential property of allowing you +to “fall back” to a stable system. But ostree will blow it out of the water.

    +
  • +
+

+ + + Development + + +

+ + + + + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/adapting-existing/index.html b/adapting-existing/index.html new file mode 100644 index 0000000000..bfb4820f4c --- /dev/null +++ b/adapting-existing/index.html @@ -0,0 +1,472 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Adapting existing mainstream distributions | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Adapting existing mainstream distributions + + +

+ + +
    +
  1. System layout
  2. +
  3. Booting and initramfs technology
  4. +
  5. System users and groups
      +
    1. Static users and groups
    2. +
    3. sysusers.d
    4. +
    +
  6. +
  7. Adapting existing package managers
  8. +
+ + +

+ + + System layout + + +

+ + +

First, OSTree encourages systems to implement +UsrMove +This is simply to avoid the need for more bind mounts. By default +OSTree’s dracut hook creates a read-only bind mount over /usr; you +can of course generate individual bind-mounts for /bin, all the +/lib variants, etc. So it is not intended to be a hard requirement.

+ +

Remember, because by default the system is booted into a chroot +equivalent, there has to be some way to refer to the actual physical +root filesystem. Therefore, your operating system tree should contain +an empty /sysroot directory; at boot time, OSTree will make this a +bind mount to the physical / root directory. There is precedent for +this name in the initramfs context. You should furthermore make a +toplevel symbolic link /ostree which points to /sysroot/ostree, so +that the OSTree tool at runtime can consistently find the system data +regardless of whether it’s operating on a physical root or inside a +deployment.

+ +

Because OSTree only preserves /var across upgrades (each +deployment’s chroot directory will be garbage collected +eventually), you will need to choose how to handle other +toplevel writable directories specified by the Filesystem Hierarchy Standard. +Your operating system may of course choose +not to support some of these such as /usr/local, but following is the +recommended set:

+ +
    +
  • /home/var/home
  • +
  • /opt/var/opt
  • +
  • /srv/var/srv
  • +
  • /root/var/roothome
  • +
  • /usr/local/var/usrlocal
  • +
  • /mnt/var/mnt
  • +
  • /tmp/sysroot/tmp
  • +
+ +

Furthermore, since /var is empty by default, your operating system +will need to dynamically create the targets of these at boot. A +good way to do this is using systemd-tmpfiles, if your OS uses +systemd. For example:

+ +
d /var/log/journal 0755 root root -
+L /var/home - - - - ../sysroot/home
+d /var/opt 0755 root root -
+d /var/srv 0755 root root -
+d /var/roothome 0700 root root -
+d /var/usrlocal 0755 root root -
+d /var/usrlocal/bin 0755 root root -
+d /var/usrlocal/etc 0755 root root -
+d /var/usrlocal/games 0755 root root -
+d /var/usrlocal/include 0755 root root -
+d /var/usrlocal/lib 0755 root root -
+d /var/usrlocal/man 0755 root root -
+d /var/usrlocal/sbin 0755 root root -
+d /var/usrlocal/share 0755 root root -
+d /var/usrlocal/src 0755 root root -
+d /var/mnt 0755 root root -
+d /run/media 0755 root root -
+
+ +

However, as of OSTree 2023.9 there is support for a root.transient +model, which can increase compatibility in some scenarios. For more +information, see man ostree-prepare-root.conf.

+ +

Particularly note here the double indirection of /home. By default, +each deployment will share the global toplevel /home directory on +the physical root filesystem. It is then up to higher levels of +management tools to keep /etc/passwd or equivalent synchronized +between operating systems. Each deployment can easily be reconfigured +to have its own home directory set simply by making /var/home a real +directory.

+

+ + + Booting and initramfs technology + + +

+ + +

OSTree comes with optional dracut+systemd integration code which follows +this logic:

+ +
    +
  • Parse the ostree= kernel command line argument in the initramfs
  • +
  • Set up a read-only bind mount on /usr
  • +
  • Bind mount the deployment’s /sysroot to the physical /
  • +
  • Use mount(MS_MOVE) to make the deployment root appear to be the root filesystem
  • +
+ +

After these steps, systemd switches root.

+ +

If you are not using dracut or systemd, using OSTree should still be +possible, but you will have to write the integration code. See the +existing sources in +src/switchroot +as a reference.

+ +

Patches to support other initramfs technologies and init systems, if +sufficiently clean, will likely be accepted upstream.

+ +

A further specific note regarding sysvinit: OSTree used to support +recording device files such as the /dev/initctl FIFO, but no longer +does. It’s recommended to just patch your initramfs to create this at +boot.

+

+ + + System users and groups + + +

+ + +

Unlike traditional package systems, OSTree trees contain numeric uid +and gids (the same is true of e.g. OCI).

+ +

Furthermore, OSTree does not have a %post type mechanism +where useradd could be invoked. In order to ship an OS that +contains both system users and users dynamically created on client +machines, you will need to choose a solution for /etc/passwd. The +core problem is that if you add a user to the system for a daemon, the +OSTree upgrade process for /etc will simply notice that because +/etc/passwd differs from the previous default, it will keep the +modified config file, and your new OS user will not be visible.

+ +

First, consider using systemd DynamicUser=yes +where applicable. This entirely avoids problems with static +allocations.

+

+ + + Static users and groups + + +

+ + +

For users which must be allocated statically (for example, they +are used by setuid executables in /usr/bin, there are two +primary wants to handle this.

+ +

The nss-altfiles +was created to pair with image-based update systems like OSTree, +and is used by many operating systems and distributions today.

+ +

More recently, nss-systemd +gained support for statically allocated users and groups in +a JSON format stored in /usr/lib/userdb.

+

+ + + sysusers.d + + +

+ + +

Some users and groups can be assigned dynamically via sysusers.d. This means users and groups are maintained per-machine and may drift (unless statically assigned in sysusers).

+ +

But this model is suitable for users and groups which must always be present, +but do not have file content in the image.

+

+ + + Adapting existing package managers + + +

+ + +

The largest endeavor is likely to be redesigning your distribution’s +package manager to be on top of OSTree, particularly if you want to +keep compatibility with the “old way” of installing into the physical +/. This section will use examples from both dpkg and rpm as the +author has familiarity with both; but the abstract concepts should +apply to most traditional package managers.

+ +

There are many levels of possible integration; initially, we will +describe the most naive implementation which is the simplest but also +the least efficient. We will assume here that the admin is booted +into an OSTree-enabled system, and wants to add a set of packages.

+ +

Many package managers store their state in /var; but since in the +OSTree model that directory is shared between independent versions, +the package database must first be found in the per-deployment /usr +directory. It becomes read-only; remember, all upgrades involve +constructing a new filesystem tree, so your package manager will also +need to create a copy of its database. Most likely, if you want to +continue supporting non-OSTree deployments, simply have your package +manager fall back to the legacy /var location if the one in /usr +is not found.

+ +

To install a set of new packages (without removing any existing ones), +enumerate the set of packages in the currently booted deployment, and +perform dependency resolution to compute the complete set of new +packages. Download and unpack these new packages to a temporary +directory.

+ +

Now, because we are merely installing new packages and not +removing anything, we can make the major optimization of reusing +our existing filesystem tree, and merely +layering the composed filesystem tree of +these new packages on top. A command like this:

+ +
ostree commit -b osname/releasename/description
+--tree=ref=$osname/$releasename/$description
+--tree=dir=/var/tmp/newpackages.13A8D0/
+
+ +

will create a new commit in the $osname/$releasename/$description +branch. The OSTree SHA256 checksum of all the files in +/var/tmp/newpackages.13A8D0/ will be computed, but we will not +re-checksum the present existing tree. In this layering model, +earlier directories will take precedence, but files in later layers +will silently override earlier layers.

+ +

Then to actually deploy this tree for the next boot: +ostree admin deploy $osname/$releasename/$description

+ +

This is essentially what rpm-ostree +does to support its package layering model.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/assets/css/just-the-docs-dark.css b/assets/css/just-the-docs-dark.css new file mode 100644 index 0000000000..58ca8a6807 --- /dev/null +++ b/assets/css/just-the-docs-dark.css @@ -0,0 +1 @@ +.highlight .c{color:#586e75}.highlight .err{color:#93a1a1}.highlight .g{color:#93a1a1}.highlight .k{color:#859900}.highlight .l{color:#93a1a1}.highlight .n{color:#93a1a1}.highlight .o{color:#859900}.highlight .x{color:#cb4b16}.highlight .p{color:#93a1a1}.highlight .cm{color:#586e75}.highlight .cp{color:#859900}.highlight .c1{color:#586e75}.highlight .cs{color:#859900}.highlight .gd{color:#2aa198}.highlight .ge{font-style:italic;color:#93a1a1}.highlight .gr{color:#dc322f}.highlight .gh{color:#cb4b16}.highlight .gi{color:#859900}.highlight .go{color:#93a1a1}.highlight .gp{color:#93a1a1}.highlight .gs{font-weight:bold;color:#93a1a1}.highlight .gu{color:#cb4b16}.highlight .gt{color:#93a1a1}.highlight .kc{color:#cb4b16}.highlight .kd{color:#268bd2}.highlight .kn{color:#859900}.highlight .kp{color:#859900}.highlight .kr{color:#268bd2}.highlight .kt{color:#dc322f}.highlight .ld{color:#93a1a1}.highlight .m{color:#2aa198}.highlight .s{color:#2aa198}.highlight .na{color:#555}.highlight .nb{color:#b58900}.highlight .nc{color:#268bd2}.highlight .no{color:#cb4b16}.highlight .nd{color:#268bd2}.highlight .ni{color:#cb4b16}.highlight .ne{color:#cb4b16}.highlight .nf{color:#268bd2}.highlight .nl{color:#555}.highlight .nn{color:#93a1a1}.highlight .nx{color:#555}.highlight .py{color:#93a1a1}.highlight .nt{color:#268bd2}.highlight .nv{color:#268bd2}.highlight .ow{color:#859900}.highlight .w{color:#93a1a1}.highlight .mf{color:#2aa198}.highlight .mh{color:#2aa198}.highlight .mi{color:#2aa198}.highlight .mo{color:#2aa198}.highlight .sb{color:#586e75}.highlight .sc{color:#2aa198}.highlight .sd{color:#93a1a1}.highlight .s2{color:#2aa198}.highlight .se{color:#cb4b16}.highlight .sh{color:#93a1a1}.highlight .si{color:#2aa198}.highlight .sx{color:#2aa198}.highlight .sr{color:#dc322f}.highlight .s1{color:#2aa198}.highlight .ss{color:#2aa198}.highlight .bp{color:#268bd2}.highlight .vc{color:#268bd2}.highlight .vg{color:#268bd2}.highlight .vi{color:#268bd2}.highlight .il{color:#2aa198}.highlight,pre.highlight{background:#31343f;color:#dee2f7}.highlight pre{background:#31343f}.highlight .hll{background:#31343f}.highlight .c{color:#63677e;font-style:italic}.highlight .err{color:#960050;background-color:#1e0010}.highlight .k{color:#e19ef5}.highlight .l{color:#a3eea0}.highlight .n{color:#dee2f7}.highlight .o{color:#dee2f7}.highlight .p{color:#dee2f7}.highlight .cm{color:#63677e;font-style:italic}.highlight .cp{color:#63677e;font-style:italic}.highlight .c1{color:#63677e;font-style:italic}.highlight .cs{color:#63677e;font-style:italic}.highlight .ge{font-style:italic}.highlight .gs{font-weight:700}.highlight .kc{color:#e19ef5}.highlight .kd{color:#e19ef5}.highlight .kn{color:#e19ef5}.highlight .kp{color:#e19ef5}.highlight .kr{color:#e19ef5}.highlight .kt{color:#e19ef5}.highlight .ld{color:#a3eea0}.highlight .m{color:#eddc96}.highlight .s{color:#a3eea0}.highlight .na{color:#eddc96}.highlight .nb{color:#fdce68}.highlight .nc{color:#fdce68}.highlight .no{color:#fdce68}.highlight .nd{color:#fdce68}.highlight .ni{color:#fdce68}.highlight .ne{color:#fdce68}.highlight .nf{color:#dee2f7}.highlight .nl{color:#fdce68}.highlight .nn{color:#dee2f7}.highlight .nx{color:#dee2f7}.highlight .py{color:#fdce68}.highlight .nt{color:#f9867b}.highlight .nv{color:#fdce68}.highlight .ow{font-weight:700}.highlight .w{color:#f8f8f2}.highlight .mf{color:#eddc96}.highlight .mh{color:#eddc96}.highlight .mi{color:#eddc96}.highlight .mo{color:#eddc96}.highlight .sb{color:#a3eea0}.highlight .sc{color:#a3eea0}.highlight .sd{color:#a3eea0}.highlight .s2{color:#a3eea0}.highlight .se{color:#a3eea0}.highlight .sh{color:#a3eea0}.highlight .si{color:#a3eea0}.highlight .sx{color:#a3eea0}.highlight .sr{color:#7be2f9}.highlight .s1{color:#a3eea0}.highlight .ss{color:#7be2f9}.highlight .bp{color:#fdce68}.highlight .vc{color:#fdce68}.highlight .vg{color:#fdce68}.highlight .vi{color:#f9867b}.highlight .il{color:#eddc96}.highlight .gu{color:#75715e}.highlight .gd{color:#f92672}.highlight .gi{color:#a6e22e}/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}main{display:block}h1{font-size:2em;margin:0.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace, monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace, monospace;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}button,[type="button"],[type="reset"],[type="submit"]{-webkit-appearance:button}button::-moz-focus-inner,[type="button"]::-moz-focus-inner,[type="reset"]::-moz-focus-inner,[type="submit"]::-moz-focus-inner{border-style:none;padding:0}button:-moz-focusring,[type="button"]:-moz-focusring,[type="reset"]:-moz-focusring,[type="submit"]:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:0.35em 0.75em 0.625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type="checkbox"],[type="radio"]{box-sizing:border-box;padding:0}[type="number"]::-webkit-inner-spin-button,[type="number"]::-webkit-outer-spin-button{height:auto}[type="search"]{-webkit-appearance:textfield;outline-offset:-2px}[type="search"]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}template{display:none}[hidden]{display:none}*{box-sizing:border-box}::selection{color:#fff;background:#2c84fa}html{font-size:14px !important;scroll-behavior:smooth}@media (min-width: 31.25rem){html{font-size:16px !important}}body{font-family:system-ui,-apple-system,blinkmacsystemfont,"Segoe UI",roboto,"Helvetica Neue",arial,sans-serif;font-size:inherit;line-height:1.4;color:#e6e1e8;background-color:#27262b;overflow-wrap:break-word}ol,ul,dl,pre,address,blockquote,table,div,hr,form,fieldset,noscript .table-wrapper{margin-top:0}h1,h2,h3,h4,h5,h6,#toctitle{margin-top:0;margin-bottom:1em;font-weight:500;line-height:1.25;color:#f5f6fa}p{margin-top:1em;margin-bottom:1em}a{color:#2c84fa;text-decoration:none}a:not([class]){text-decoration:underline;text-decoration-color:#44434d;text-underline-offset:2px}a:not([class]):hover{text-decoration-color:rgba(44,132,250,0.45)}code{font-family:"SFMono-Regular",menlo,consolas,monospace;font-size:0.75em;line-height:1.4}figure,pre{margin:0}li{margin:0.25em 0}img{max-width:100%;height:auto}hr{height:1px;padding:0;margin:2rem 0;background-color:#44434d;border:0}blockquote{margin:10px 0;margin-block-start:0;margin-inline-start:0;padding-left:15px;border-left:3px solid #44434d}.side-bar{z-index:0;display:flex;flex-wrap:wrap;background-color:#27262b}@media (min-width: 50rem){.side-bar{flex-flow:column nowrap;position:fixed;width:248px;height:100%;border-right:1px solid #44434d;align-items:flex-end}}@media (min-width: 66.5rem){.side-bar{width:calc((100% - 1064px) / 2 + 264px);min-width:264px}}@media (min-width: 50rem){.main{position:relative;max-width:800px;margin-left:248px}}@media (min-width: 66.5rem){.main{margin-left:Max(264px, calc((100% - 1064px) / 2 + 264px))}}.main-content-wrap{padding-right:1rem;padding-left:1rem;padding-top:1rem;padding-bottom:1rem}@media (min-width: 50rem){.main-content-wrap{padding-right:2rem;padding-left:2rem}}@media (min-width: 50rem){.main-content-wrap{padding-top:2rem;padding-bottom:2rem}}.main-header{z-index:0;display:none;background-color:#27262b}@media (min-width: 50rem){.main-header{display:flex;justify-content:space-between;height:60px;background-color:#27262b;border-bottom:1px solid #44434d}}.main-header.nav-open{display:block}@media (min-width: 50rem){.main-header.nav-open{display:flex}}.site-nav,.site-header,.site-footer{width:100%}@media (min-width: 66.5rem){.site-nav,.site-header,.site-footer{width:264px}}.site-nav{display:none}.site-nav.nav-open{display:block}@media (min-width: 50rem){.site-nav{display:block;padding-top:3rem;padding-bottom:1rem;overflow-y:auto;flex:1 1 auto}}.site-header{display:flex;min-height:60px;align-items:center}@media (min-width: 50rem){.site-header{height:60px;max-height:60px;border-bottom:1px solid #44434d}}.site-title{padding-right:1rem;padding-left:1rem;flex-grow:1;display:flex;height:100%;align-items:center;padding-top:.75rem;padding-bottom:.75rem;color:#f5f6fa;font-size:18px !important}@media (min-width: 50rem){.site-title{padding-right:2rem;padding-left:2rem}}@media (min-width: 31.25rem){.site-title{font-size:24px !important;line-height:1.25}}@media (min-width: 50rem){.site-title{padding-top:.5rem;padding-bottom:.5rem}}.site-button{display:flex;height:100%;padding:1rem;align-items:center}@media (min-width: 50rem){.site-header .site-button{display:none}}.site-title:hover{background-image:linear-gradient(-90deg, #201f23 0%, rgba(32,31,35,0.8) 80%, rgba(32,31,35,0) 100%)}.site-button:hover{background-image:linear-gradient(-90deg, #201f23 0%, rgba(32,31,35,0.8) 100%)}body{position:relative;padding-bottom:4rem;overflow-y:scroll}@media (min-width: 50rem){body{position:static;padding-bottom:0}}.site-footer{padding-right:1rem;padding-left:1rem;position:absolute;bottom:0;left:0;padding-top:1rem;padding-bottom:1rem;color:#959396;font-size:11px !important}@media (min-width: 50rem){.site-footer{padding-right:2rem;padding-left:2rem}}@media (min-width: 31.25rem){.site-footer{font-size:12px !important}}@media (min-width: 50rem){.site-footer{position:static;justify-self:end}}.icon{width:1.5rem;height:1.5rem;color:#2c84fa}.main-content{line-height:1.6}.main-content ol,.main-content ul,.main-content dl,.main-content pre,.main-content address,.main-content blockquote,.main-content .table-wrapper{margin-top:0.5em}.main-content a{overflow:hidden;text-overflow:ellipsis}.main-content ul,.main-content ol{padding-left:1.5em}.main-content li .highlight{margin-top:.25rem}.main-content ol{list-style-type:none;counter-reset:step-counter}.main-content ol>li{position:relative}.main-content ol>li::before{position:absolute;top:0.2em;left:-1.6em;color:#959396;content:counter(step-counter);counter-increment:step-counter;font-size:12px !important}@media (min-width: 31.25rem){.main-content ol>li::before{font-size:14px !important}}@media (min-width: 31.25rem){.main-content ol>li::before{top:0.11em}}.main-content ol>li ol{counter-reset:sub-counter}.main-content ol>li ol>li::before{content:counter(sub-counter,lower-alpha);counter-increment:sub-counter}.main-content ul{list-style:none}.main-content ul>li::before{position:absolute;margin-left:-1.4em;color:#959396;content:"•"}.main-content .task-list-item::before{content:""}.main-content .task-list-item-checkbox{margin-right:0.6em;margin-left:-1.4em}.main-content hr+*{margin-top:0}.main-content h1:first-of-type{margin-top:0.5em}.main-content dl{display:grid;grid-template:auto / 10em 1fr}.main-content dt,.main-content dd{margin:0.25em 0}.main-content dt{grid-column:1;font-weight:500;text-align:right}.main-content dt::after{content:":"}.main-content dd{grid-column:2;margin-bottom:0;margin-left:1em}.main-content dd blockquote:first-child,.main-content dd div:first-child,.main-content dd dl:first-child,.main-content dd dt:first-child,.main-content dd h1:first-child,.main-content dd h2:first-child,.main-content dd h3:first-child,.main-content dd h4:first-child,.main-content dd h5:first-child,.main-content dd h6:first-child,.main-content dd li:first-child,.main-content dd ol:first-child,.main-content dd p:first-child,.main-content dd pre:first-child,.main-content dd table:first-child,.main-content dd ul:first-child,.main-content dd .table-wrapper:first-child{margin-top:0}.main-content dd dl:first-child dt:first-child,.main-content dd dl:first-child dd:nth-child(2),.main-content ol dl:first-child dt:first-child,.main-content ol dl:first-child dd:nth-child(2),.main-content ul dl:first-child dt:first-child,.main-content ul dl:first-child dd:nth-child(2){margin-top:0}.main-content .anchor-heading{position:absolute;right:-1rem;width:1.5rem;height:100%;padding-right:.25rem;padding-left:.25rem;overflow:visible}@media (min-width: 50rem){.main-content .anchor-heading{right:auto;left:-1.5rem}}.main-content .anchor-heading svg{display:inline-block;width:100%;height:100%;color:#2c84fa;visibility:hidden}.main-content .anchor-heading:hover svg,.main-content .anchor-heading:focus svg,.main-content h1:hover>.anchor-heading svg,.main-content h2:hover>.anchor-heading svg,.main-content h3:hover>.anchor-heading svg,.main-content h4:hover>.anchor-heading svg,.main-content h5:hover>.anchor-heading svg,.main-content h6:hover>.anchor-heading svg{visibility:visible}.main-content summary{cursor:pointer}.main-content h1,.main-content h2,.main-content h3,.main-content h4,.main-content h5,.main-content h6,.main-content #toctitle{position:relative;margin-top:1.5em;margin-bottom:0.25em}.main-content h1+table,.main-content h1+.table-wrapper,.main-content h1+.code-example,.main-content h1+.highlighter-rouge,.main-content h1+.sectionbody .listingblock,.main-content h2+table,.main-content h2+.table-wrapper,.main-content h2+.code-example,.main-content h2+.highlighter-rouge,.main-content h2+.sectionbody .listingblock,.main-content h3+table,.main-content h3+.table-wrapper,.main-content h3+.code-example,.main-content h3+.highlighter-rouge,.main-content h3+.sectionbody .listingblock,.main-content h4+table,.main-content h4+.table-wrapper,.main-content h4+.code-example,.main-content h4+.highlighter-rouge,.main-content h4+.sectionbody .listingblock,.main-content h5+table,.main-content h5+.table-wrapper,.main-content h5+.code-example,.main-content h5+.highlighter-rouge,.main-content h5+.sectionbody .listingblock,.main-content h6+table,.main-content h6+.table-wrapper,.main-content h6+.code-example,.main-content h6+.highlighter-rouge,.main-content h6+.sectionbody .listingblock,.main-content #toctitle+table,.main-content #toctitle+.table-wrapper,.main-content #toctitle+.code-example,.main-content #toctitle+.highlighter-rouge,.main-content #toctitle+.sectionbody .listingblock{margin-top:1em}.main-content h1+p:not(.label),.main-content h2+p:not(.label),.main-content h3+p:not(.label),.main-content h4+p:not(.label),.main-content h5+p:not(.label),.main-content h6+p:not(.label),.main-content #toctitle+p:not(.label){margin-top:0}.main-content>h1:first-child,.main-content>h2:first-child,.main-content>h3:first-child,.main-content>h4:first-child,.main-content>h5:first-child,.main-content>h6:first-child,.main-content>.sect1:first-child>h2,.main-content>.sect2:first-child>h3,.main-content>.sect3:first-child>h4,.main-content>.sect4:first-child>h5,.main-content>.sect5:first-child>h6{margin-top:.5rem}.nav-list{padding:0;margin-top:0;margin-bottom:0;list-style:none}.nav-list .nav-list-item{font-size:14px !important;position:relative;margin:0}@media (min-width: 31.25rem){.nav-list .nav-list-item{font-size:16px !important}}@media (min-width: 50rem){.nav-list .nav-list-item{font-size:12px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.nav-list .nav-list-item{font-size:14px !important}}.nav-list .nav-list-item .nav-list-link{display:block;min-height:3rem;padding-top:.25rem;padding-bottom:.25rem;line-height:2.5rem;padding-right:3rem;padding-left:1rem}@media (min-width: 50rem){.nav-list .nav-list-item .nav-list-link{min-height:2rem;line-height:1.5rem;padding-right:2rem;padding-left:2rem}}.nav-list .nav-list-item .nav-list-link.external>svg{width:1rem;height:1rem;vertical-align:text-bottom}.nav-list .nav-list-item .nav-list-link.active{font-weight:600;text-decoration:none}.nav-list .nav-list-item .nav-list-link:hover,.nav-list .nav-list-item .nav-list-link.active{background-image:linear-gradient(-90deg, #201f23 0%, rgba(32,31,35,0.8) 80%, rgba(32,31,35,0) 100%)}.nav-list .nav-list-item .nav-list-expander{position:absolute;right:0;width:3rem;height:3rem;padding:.75rem;color:#2c84fa}@media (min-width: 50rem){.nav-list .nav-list-item .nav-list-expander{width:2rem;height:2rem;padding:.5rem}}.nav-list .nav-list-item .nav-list-expander:hover{background-image:linear-gradient(-90deg, #201f23 0%, rgba(32,31,35,0.8) 100%)}.nav-list .nav-list-item .nav-list-expander svg{transform:rotate(90deg)}.nav-list .nav-list-item>.nav-list{display:none;padding-left:.75rem;list-style:none}.nav-list .nav-list-item>.nav-list .nav-list-item{position:relative}.nav-list .nav-list-item>.nav-list .nav-list-item .nav-list-link{color:#959396}.nav-list .nav-list-item>.nav-list .nav-list-item .nav-list-expander{color:#959396}.nav-list .nav-list-item.active>.nav-list-expander svg{transform:rotate(-90deg)}.nav-list .nav-list-item.active>.nav-list{display:block}.nav-category{padding:.5rem 1rem;font-weight:600;text-align:start;text-transform:uppercase;border-bottom:1px solid #44434d;font-size:11px !important}@media (min-width: 31.25rem){.nav-category{font-size:12px !important}}@media (min-width: 50rem){.nav-category{padding:.5rem 2rem;margin-top:1rem;text-align:start}.nav-category:first-child{margin-top:0}}.nav-list.nav-category-list>.nav-list-item{margin:0}.nav-list.nav-category-list>.nav-list-item>.nav-list{padding:0}.nav-list.nav-category-list>.nav-list-item>.nav-list>.nav-list-item>.nav-list-link{color:#2c84fa}.nav-list.nav-category-list>.nav-list-item>.nav-list>.nav-list-item>.nav-list-expander{color:#2c84fa}.aux-nav{height:100%;overflow-x:auto;font-size:11px !important}@media (min-width: 31.25rem){.aux-nav{font-size:12px !important}}.aux-nav .aux-nav-list{display:flex;height:100%;padding:0;margin:0;list-style:none}.aux-nav .aux-nav-list-item{display:inline-block;height:100%;padding:0;margin:0}@media (min-width: 50rem){.aux-nav{padding-right:1rem}}@media (min-width: 50rem){.breadcrumb-nav{margin-top:-1rem}}.breadcrumb-nav-list{padding-left:0;margin-bottom:.75rem;list-style:none}.breadcrumb-nav-list-item{display:table-cell;font-size:11px !important}@media (min-width: 31.25rem){.breadcrumb-nav-list-item{font-size:12px !important}}.breadcrumb-nav-list-item::before{display:none}.breadcrumb-nav-list-item::after{display:inline-block;margin-right:.5rem;margin-left:.5rem;color:#959396;content:"/"}.breadcrumb-nav-list-item:last-child::after{content:""}h1,.text-alpha{font-size:32px !important;line-height:1.25;font-weight:300}@media (min-width: 31.25rem){h1,.text-alpha{font-size:36px !important}}h2,.text-beta,#toctitle{font-size:18px !important}@media (min-width: 31.25rem){h2,.text-beta,#toctitle{font-size:24px !important;line-height:1.25}}h3,.text-gamma{font-size:16px !important}@media (min-width: 31.25rem){h3,.text-gamma{font-size:18px !important}}h4,.text-delta{font-size:11px !important;font-weight:400;text-transform:uppercase;letter-spacing:0.1em}@media (min-width: 31.25rem){h4,.text-delta{font-size:12px !important}}h4 code{text-transform:none}h5,.text-epsilon{font-size:12px !important}@media (min-width: 31.25rem){h5,.text-epsilon{font-size:14px !important}}h6,.text-zeta{font-size:11px !important}@media (min-width: 31.25rem){h6,.text-zeta{font-size:12px !important}}.text-small{font-size:11px !important}@media (min-width: 31.25rem){.text-small{font-size:12px !important}}.text-mono{font-family:"SFMono-Regular",menlo,consolas,monospace !important}.text-left{text-align:left !important}.text-center{text-align:center !important}.text-right{text-align:right !important}.label,.label-blue{display:inline-block;padding:0.16em 0.56em;margin-right:.5rem;margin-left:.5rem;color:#fff;text-transform:uppercase;vertical-align:middle;background-color:#2869e6;font-size:11px !important;border-radius:12px}@media (min-width: 31.25rem){.label,.label-blue{font-size:12px !important}}.label-green{background-color:#009c7b}.label-purple{background-color:#5e41d0}.label-red{background-color:#e94c4c}.label-yellow{color:#44434d;background-color:#f7d12e}.btn{display:inline-block;box-sizing:border-box;padding:0.3em 1em;margin:0;font-family:inherit;font-size:inherit;font-weight:500;line-height:1.5;color:#2c84fa;text-decoration:none;vertical-align:baseline;cursor:pointer;background-color:#302d36;border-width:0;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);appearance:none}.btn:focus{text-decoration:none;outline:none;box-shadow:0 0 0 3px rgba(0,0,255,0.25)}.btn:focus:hover,.btn.selected:focus{box-shadow:0 0 0 3px rgba(0,0,255,0.25)}.btn:hover,.btn.zeroclipboard-is-hover{color:#227efa}.btn:hover,.btn:active,.btn.zeroclipboard-is-hover,.btn.zeroclipboard-is-active{text-decoration:none;background-color:#2e2b33}.btn:active,.btn.selected,.btn.zeroclipboard-is-active{background-color:#29262e;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn.selected:hover{background-color:#cfcfcf}.btn:disabled,.btn:disabled:hover,.btn.disabled,.btn.disabled:hover{color:rgba(102,102,102,0.5);cursor:default;background-color:rgba(229,229,229,0.5);background-image:none;box-shadow:none}.btn-outline{color:#2c84fa;background:transparent;box-shadow:inset 0 0 0 2px #e6e1e8}.btn-outline:hover,.btn-outline:active,.btn-outline.zeroclipboard-is-hover,.btn-outline.zeroclipboard-is-active{color:#1878fa;text-decoration:none;background-color:transparent;box-shadow:inset 0 0 0 3px #e6e1e8}.btn-outline:focus{text-decoration:none;outline:none;box-shadow:inset 0 0 0 2px #5c5962,0 0 0 3px rgba(0,0,255,0.25)}.btn-outline:focus:hover,.btn-outline.selected:focus{box-shadow:inset 0 0 0 2px #5c5962}.btn-primary{color:#fff;background-color:#2448a7;background-image:linear-gradient(#2b55c4, #2448a7);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-primary:hover,.btn-primary.zeroclipboard-is-hover{color:#fff;background-color:#22459e;background-image:linear-gradient(#2850b7,#22459e)}.btn-primary:active,.btn-primary.selected,.btn-primary.zeroclipboard-is-active{background-color:#21439a;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-primary.selected:hover{background-color:#1d3a85}.btn-purple{color:#fff;background-color:#5739ce;background-image:linear-gradient(#6f55d5, #5739ce);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-purple:hover,.btn-purple.zeroclipboard-is-hover{color:#fff;background-color:#5132cb;background-image:linear-gradient(#6549d2,#5132cb)}.btn-purple:active,.btn-purple.selected,.btn-purple.zeroclipboard-is-active{background-color:#4f31c6;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-purple.selected:hover{background-color:#472cb2}.btn-blue{color:#fff;background-color:#227efa;background-image:linear-gradient(#4593fb, #227efa);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-blue:hover,.btn-blue.zeroclipboard-is-hover{color:#fff;background-color:#1878fa;background-image:linear-gradient(#368afa,#1878fa)}.btn-blue:active,.btn-blue.selected,.btn-blue.zeroclipboard-is-active{background-color:#1375f9;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-blue.selected:hover{background-color:#0669ed}.btn-green{color:#fff;background-color:#10ac7d;background-image:linear-gradient(#13cc95, #10ac7d);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-green:hover,.btn-green.zeroclipboard-is-hover{color:#fff;background-color:#0fa276;background-image:linear-gradient(#12be8b,#0fa276)}.btn-green:active,.btn-green.selected,.btn-green.zeroclipboard-is-active{background-color:#0f9e73;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-green.selected:hover{background-color:#0d8662}.search{position:relative;z-index:2;flex-grow:1;height:4rem;padding:.5rem;transition:padding linear 200ms}@media (min-width: 50rem){.search{position:relative !important;width:auto !important;height:100% !important;padding:0;transition:none}}.search-input-wrap{position:relative;z-index:1;height:3rem;overflow:hidden;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);transition:height linear 200ms}@media (min-width: 50rem){.search-input-wrap{position:absolute;width:100%;max-width:536px;height:100% !important;border-radius:0;box-shadow:none;transition:width ease 400ms}}.search-input{position:absolute;width:100%;height:100%;padding:.5rem 1rem .5rem 2.5rem;font-size:16px;color:#e6e1e8;background-color:#302d36;border-top:0;border-right:0;border-bottom:0;border-left:0;border-radius:0}@media (min-width: 50rem){.search-input{padding:.5rem 1rem .5rem 3.5rem;font-size:14px;background-color:#27262b;transition:padding-left linear 200ms}}.search-input:focus{outline:0}.search-input:focus+.search-label .search-icon{color:#2c84fa}.search-label{position:absolute;display:flex;height:100%;padding-left:1rem}@media (min-width: 50rem){.search-label{padding-left:2rem;transition:padding-left linear 200ms}}.search-label .search-icon{width:1.2rem;height:1.2rem;align-self:center;color:#959396}.search-results{position:absolute;left:0;display:none;width:100%;max-height:calc(100% - 4rem);overflow-y:auto;background-color:#302d36;border-bottom-right-radius:4px;border-bottom-left-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}@media (min-width: 50rem){.search-results{top:100%;width:536px;max-height:calc(100vh - 200%) !important}}.search-results-list{padding-left:0;margin-bottom:.25rem;list-style:none;font-size:14px !important}@media (min-width: 31.25rem){.search-results-list{font-size:16px !important}}@media (min-width: 50rem){.search-results-list{font-size:12px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.search-results-list{font-size:14px !important}}.search-results-list-item{padding:0;margin:0}.search-result{display:block;padding:.25rem .75rem}.search-result:hover,.search-result.active{background-color:#201f23}.search-result-title{display:block;padding-top:.5rem;padding-bottom:.5rem}@media (min-width: 31.25rem){.search-result-title{display:inline-block;width:40%;padding-right:.5rem;vertical-align:top}}.search-result-doc{display:flex;align-items:center;word-wrap:break-word}.search-result-doc.search-result-doc-parent{opacity:0.5;font-size:12px !important}@media (min-width: 31.25rem){.search-result-doc.search-result-doc-parent{font-size:14px !important}}@media (min-width: 50rem){.search-result-doc.search-result-doc-parent{font-size:11px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.search-result-doc.search-result-doc-parent{font-size:12px !important}}.search-result-doc .search-result-icon{width:1rem;height:1rem;margin-right:.5rem;color:#2c84fa;flex-shrink:0}.search-result-doc .search-result-doc-title{overflow:auto}.search-result-section{margin-left:1.5rem;word-wrap:break-word}.search-result-rel-url{display:block;margin-left:1.5rem;overflow:hidden;color:#959396;text-overflow:ellipsis;white-space:nowrap;font-size:9px !important}@media (min-width: 31.25rem){.search-result-rel-url{font-size:10px !important}}.search-result-previews{display:block;padding-top:.5rem;padding-bottom:.5rem;padding-left:1rem;margin-left:.5rem;color:#959396;word-wrap:break-word;border-left:1px solid;border-left-color:#44434d;font-size:11px !important}@media (min-width: 31.25rem){.search-result-previews{font-size:12px !important}}@media (min-width: 31.25rem){.search-result-previews{display:inline-block;width:60%;padding-left:.5rem;margin-left:0;vertical-align:top}}.search-result-preview+.search-result-preview{margin-top:.25rem}.search-result-highlight{font-weight:bold}.search-no-result{padding:.5rem .75rem;font-size:12px !important}@media (min-width: 31.25rem){.search-no-result{font-size:14px !important}}.search-button{position:fixed;right:1rem;bottom:1rem;display:flex;width:3.5rem;height:3.5rem;background-color:#302d36;border:1px solid rgba(44,132,250,0.3);border-radius:1.75rem;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);align-items:center;justify-content:center}.search-overlay{position:fixed;top:0;left:0;z-index:1;width:0;height:0;background-color:rgba(0,0,0,0.3);opacity:0;transition:opacity ease 400ms,width 0s 400ms,height 0s 400ms}.search-active .search{position:fixed;top:0;left:0;width:100%;height:100%;padding:0}.search-active .search-input-wrap{height:4rem;border-radius:0}@media (min-width: 50rem){.search-active .search-input-wrap{width:536px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}}.search-active .search-input{background-color:#302d36}@media (min-width: 50rem){.search-active .search-input{padding-left:2.3rem}}@media (min-width: 50rem){.search-active .search-label{padding-left:0.6rem}}.search-active .search-results{display:block}.search-active .search-overlay{width:100%;height:100%;opacity:1;transition:opacity ease 400ms,width 0s,height 0s}@media (min-width: 50rem){.search-active .main{position:fixed;right:0;left:0}}.search-active .main-header{padding-top:4rem}@media (min-width: 50rem){.search-active .main-header{padding-top:0}}.table-wrapper{display:block;width:100%;max-width:100%;margin-bottom:1.5rem;overflow-x:auto;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}table{display:table;min-width:100%;border-collapse:separate}th,td{font-size:12px !important;min-width:120px;padding:.5rem .75rem;background-color:#302d36;border-bottom:1px solid rgba(68,67,77,0.5);border-left:1px solid #44434d}@media (min-width: 31.25rem){th,td{font-size:14px !important}}th:first-of-type,td:first-of-type{border-left:0}tbody tr:last-of-type th,tbody tr:last-of-type td{border-bottom:0}tbody tr:last-of-type td{padding-bottom:.75rem}thead th{border-bottom:1px solid #44434d}:not(pre,figure)>code{padding:0.2em 0.15em;font-weight:400;background-color:#31343f;border:1px solid #44434d;border-radius:4px}a:visited code{border-color:#44434d}div.highlighter-rouge,div.listingblock>div.content,figure.highlight{margin-top:0;margin-bottom:.75rem;background-color:#31343f;border-radius:4px;box-shadow:none;-webkit-overflow-scrolling:touch;position:relative;padding:0}div.highlighter-rouge>button,div.listingblock>div.content>button,figure.highlight>button{width:.75rem;opacity:0;position:absolute;top:0;right:0;border:.75rem solid #31343f;background-color:#31343f;color:#e6e1e8;box-sizing:content-box}div.highlighter-rouge>button svg,div.listingblock>div.content>button svg,figure.highlight>button svg{fill:#e6e1e8}div.highlighter-rouge>button:active,div.listingblock>div.content>button:active,figure.highlight>button:active{text-decoration:none;outline:none;opacity:1}div.highlighter-rouge>button:focus,div.listingblock>div.content>button:focus,figure.highlight>button:focus{opacity:1}div.highlighter-rouge:hover>button,div.listingblock>div.content:hover>button,figure.highlight:hover>button{cursor:copy;opacity:1}div.highlighter-rouge div.highlight{overflow-x:auto;padding:.75rem;margin:0;border:0}div.highlighter-rouge pre.highlight,div.highlighter-rouge code{padding:0;margin:0;border:0}div.listingblock{margin-top:0;margin-bottom:.75rem}div.listingblock div.content{overflow-x:auto;padding:.75rem;margin:0;border:0}div.listingblock div.content>pre,div.listingblock code{padding:0;margin:0;border:0}figure.highlight pre,figure.highlight :not(pre)>code{overflow-x:auto;padding:.75rem;margin:0;border:0}.highlight .table-wrapper{padding:.75rem 0;margin:0;border:0;box-shadow:none}.highlight .table-wrapper td,.highlight .table-wrapper pre{font-size:11px !important;min-width:0;padding:0;background-color:#31343f;border:0}@media (min-width: 31.25rem){.highlight .table-wrapper td,.highlight .table-wrapper pre{font-size:12px !important}}.highlight .table-wrapper td.gl{width:1em;padding-right:.75rem;padding-left:.75rem}.highlight .table-wrapper pre{margin:0;line-height:2}.code-example,.listingblock>.title{padding:.75rem;margin-bottom:.75rem;overflow:auto;border:1px solid #44434d;border-radius:4px}.code-example+.highlighter-rouge,.code-example+.sectionbody .listingblock,.code-example+.content,.code-example+figure.highlight,.listingblock>.title+.highlighter-rouge,.listingblock>.title+.sectionbody .listingblock,.listingblock>.title+.content,.listingblock>.title+figure.highlight{position:relative;margin-top:-1rem;border-right:1px solid #44434d;border-bottom:1px solid #44434d;border-left:1px solid #44434d;border-top-left-radius:0;border-top-right-radius:0}code.language-mermaid{padding:0;background-color:inherit;border:0}.highlight,pre.highlight{background:#31343f;color:#dee2f7}.highlight pre{background:#31343f}.text-grey-dk-000{color:#959396 !important}.text-grey-dk-100{color:#5c5962 !important}.text-grey-dk-200{color:#44434d !important}.text-grey-dk-250{color:#302d36 !important}.text-grey-dk-300{color:#27262b !important}.text-grey-lt-000{color:#f5f6fa !important}.text-grey-lt-100{color:#eeebee !important}.text-grey-lt-200{color:#ecebed !important}.text-grey-lt-300{color:#e6e1e8 !important}.text-blue-000{color:#2c84fa !important}.text-blue-100{color:#2869e6 !important}.text-blue-200{color:#264caf !important}.text-blue-300{color:#183385 !important}.text-green-000{color:#41d693 !important}.text-green-100{color:#11b584 !important}.text-green-200{color:#009c7b !important}.text-green-300{color:#026e57 !important}.text-purple-000{color:#7253ed !important}.text-purple-100{color:#5e41d0 !important}.text-purple-200{color:#4e26af !important}.text-purple-300{color:#381885 !important}.text-yellow-000{color:#ffeb82 !important}.text-yellow-100{color:#fadf50 !important}.text-yellow-200{color:#f7d12e !important}.text-yellow-300{color:#e7af06 !important}.text-red-000{color:#f77e7e !important}.text-red-100{color:#f96e65 !important}.text-red-200{color:#e94c4c !important}.text-red-300{color:#dd2e2e !important}.bg-grey-dk-000{background-color:#959396 !important}.bg-grey-dk-100{background-color:#5c5962 !important}.bg-grey-dk-200{background-color:#44434d !important}.bg-grey-dk-250{background-color:#302d36 !important}.bg-grey-dk-300{background-color:#27262b !important}.bg-grey-lt-000{background-color:#f5f6fa !important}.bg-grey-lt-100{background-color:#eeebee !important}.bg-grey-lt-200{background-color:#ecebed !important}.bg-grey-lt-300{background-color:#e6e1e8 !important}.bg-blue-000{background-color:#2c84fa !important}.bg-blue-100{background-color:#2869e6 !important}.bg-blue-200{background-color:#264caf !important}.bg-blue-300{background-color:#183385 !important}.bg-green-000{background-color:#41d693 !important}.bg-green-100{background-color:#11b584 !important}.bg-green-200{background-color:#009c7b !important}.bg-green-300{background-color:#026e57 !important}.bg-purple-000{background-color:#7253ed !important}.bg-purple-100{background-color:#5e41d0 !important}.bg-purple-200{background-color:#4e26af !important}.bg-purple-300{background-color:#381885 !important}.bg-yellow-000{background-color:#ffeb82 !important}.bg-yellow-100{background-color:#fadf50 !important}.bg-yellow-200{background-color:#f7d12e !important}.bg-yellow-300{background-color:#e7af06 !important}.bg-red-000{background-color:#f77e7e !important}.bg-red-100{background-color:#f96e65 !important}.bg-red-200{background-color:#e94c4c !important}.bg-red-300{background-color:#dd2e2e !important}.d-block{display:block !important}.d-flex{display:flex !important}.d-inline{display:inline !important}.d-inline-block{display:inline-block !important}.d-none{display:none !important}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}.float-left{float:left !important}.float-right{float:right !important}.flex-justify-start{justify-content:flex-start !important}.flex-justify-end{justify-content:flex-end !important}.flex-justify-between{justify-content:space-between !important}.flex-justify-around{justify-content:space-around !important}.v-align-baseline{vertical-align:baseline !important}.v-align-bottom{vertical-align:bottom !important}.v-align-middle{vertical-align:middle !important}.v-align-text-bottom{vertical-align:text-bottom !important}.v-align-text-top{vertical-align:text-top !important}.v-align-top{vertical-align:top !important}.fs-1{font-size:9px !important}@media (min-width: 31.25rem){.fs-1{font-size:10px !important}}.fs-2{font-size:11px !important}@media (min-width: 31.25rem){.fs-2{font-size:12px !important}}.fs-3{font-size:12px !important}@media (min-width: 31.25rem){.fs-3{font-size:14px !important}}.fs-4{font-size:14px !important}@media (min-width: 31.25rem){.fs-4{font-size:16px !important}}.fs-5{font-size:16px !important}@media (min-width: 31.25rem){.fs-5{font-size:18px !important}}.fs-6{font-size:18px !important}@media (min-width: 31.25rem){.fs-6{font-size:24px !important;line-height:1.25}}.fs-7{font-size:24px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-7{font-size:32px !important}}.fs-8{font-size:32px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-8{font-size:36px !important}}.fs-9{font-size:36px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-9{font-size:42px !important}}.fs-10{font-size:42px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-10{font-size:48px !important}}.fw-300{font-weight:300 !important}.fw-400{font-weight:400 !important}.fw-500{font-weight:500 !important}.fw-700{font-weight:700 !important}.lh-0{line-height:0 !important}.lh-default{line-height:1.4}.lh-tight{line-height:1.25}.ls-5{letter-spacing:0.05em !important}.ls-10{letter-spacing:0.1em !important}.ls-0{letter-spacing:0 !important}.text-uppercase{text-transform:uppercase !important}.list-style-none{padding:0 !important;margin:0 !important;list-style:none !important}.list-style-none li::before{display:none !important}.mx-auto{margin-right:auto !important;margin-left:auto !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-right:0 !important;margin-left:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-0{margin-right:-0 !important;margin-left:-0 !important}.mx-0-auto{margin-right:auto !important;margin-left:auto !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-1{margin-right:-.25rem !important;margin-left:-.25rem !important}.mx-1-auto{margin-right:auto !important;margin-left:auto !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-2{margin-right:-.5rem !important;margin-left:-.5rem !important}.mx-2-auto{margin-right:auto !important;margin-left:auto !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-3{margin-right:-.75rem !important;margin-left:-.75rem !important}.mx-3-auto{margin-right:auto !important;margin-left:auto !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-right:1rem !important;margin-left:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-4{margin-right:-1rem !important;margin-left:-1rem !important}.mx-4-auto{margin-right:auto !important;margin-left:auto !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}.mx-5-auto{margin-right:auto !important;margin-left:auto !important}.m-6{margin:2rem !important}.mt-6{margin-top:2rem !important}.mr-6{margin-right:2rem !important}.mb-6{margin-bottom:2rem !important}.ml-6{margin-left:2rem !important}.mx-6{margin-right:2rem !important;margin-left:2rem !important}.my-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-6{margin-right:-2rem !important;margin-left:-2rem !important}.mx-6-auto{margin-right:auto !important;margin-left:auto !important}.m-7{margin:2.5rem !important}.mt-7{margin-top:2.5rem !important}.mr-7{margin-right:2.5rem !important}.mb-7{margin-bottom:2.5rem !important}.ml-7{margin-left:2.5rem !important}.mx-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}.mx-7-auto{margin-right:auto !important;margin-left:auto !important}.m-8{margin:3rem !important}.mt-8{margin-top:3rem !important}.mr-8{margin-right:3rem !important}.mb-8{margin-bottom:3rem !important}.ml-8{margin-left:3rem !important}.mx-8{margin-right:3rem !important;margin-left:3rem !important}.my-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-8{margin-right:-3rem !important;margin-left:-3rem !important}.mx-8-auto{margin-right:auto !important;margin-left:auto !important}.m-9{margin:3.5rem !important}.mt-9{margin-top:3.5rem !important}.mr-9{margin-right:3.5rem !important}.mb-9{margin-bottom:3.5rem !important}.ml-9{margin-left:3.5rem !important}.mx-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}.mx-9-auto{margin-right:auto !important;margin-left:auto !important}.m-10{margin:4rem !important}.mt-10{margin-top:4rem !important}.mr-10{margin-right:4rem !important}.mb-10{margin-bottom:4rem !important}.ml-10{margin-left:4rem !important}.mx-10{margin-right:4rem !important;margin-left:4rem !important}.my-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-10{margin-right:-4rem !important;margin-left:-4rem !important}.mx-10-auto{margin-right:auto !important;margin-left:auto !important}@media (min-width: 20rem){.m-xs-0{margin:0 !important}.mt-xs-0{margin-top:0 !important}.mr-xs-0{margin-right:0 !important}.mb-xs-0{margin-bottom:0 !important}.ml-xs-0{margin-left:0 !important}.mx-xs-0{margin-right:0 !important;margin-left:0 !important}.my-xs-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-xs-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 20rem){.m-xs-1{margin:.25rem !important}.mt-xs-1{margin-top:.25rem !important}.mr-xs-1{margin-right:.25rem !important}.mb-xs-1{margin-bottom:.25rem !important}.ml-xs-1{margin-left:.25rem !important}.mx-xs-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-xs-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-xs-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 20rem){.m-xs-2{margin:.5rem !important}.mt-xs-2{margin-top:.5rem !important}.mr-xs-2{margin-right:.5rem !important}.mb-xs-2{margin-bottom:.5rem !important}.ml-xs-2{margin-left:.5rem !important}.mx-xs-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-xs-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-xs-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 20rem){.m-xs-3{margin:.75rem !important}.mt-xs-3{margin-top:.75rem !important}.mr-xs-3{margin-right:.75rem !important}.mb-xs-3{margin-bottom:.75rem !important}.ml-xs-3{margin-left:.75rem !important}.mx-xs-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-xs-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-xs-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 20rem){.m-xs-4{margin:1rem !important}.mt-xs-4{margin-top:1rem !important}.mr-xs-4{margin-right:1rem !important}.mb-xs-4{margin-bottom:1rem !important}.ml-xs-4{margin-left:1rem !important}.mx-xs-4{margin-right:1rem !important;margin-left:1rem !important}.my-xs-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-xs-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 20rem){.m-xs-5{margin:1.5rem !important}.mt-xs-5{margin-top:1.5rem !important}.mr-xs-5{margin-right:1.5rem !important}.mb-xs-5{margin-bottom:1.5rem !important}.ml-xs-5{margin-left:1.5rem !important}.mx-xs-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-xs-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-xs-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 20rem){.m-xs-6{margin:2rem !important}.mt-xs-6{margin-top:2rem !important}.mr-xs-6{margin-right:2rem !important}.mb-xs-6{margin-bottom:2rem !important}.ml-xs-6{margin-left:2rem !important}.mx-xs-6{margin-right:2rem !important;margin-left:2rem !important}.my-xs-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-xs-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 20rem){.m-xs-7{margin:2.5rem !important}.mt-xs-7{margin-top:2.5rem !important}.mr-xs-7{margin-right:2.5rem !important}.mb-xs-7{margin-bottom:2.5rem !important}.ml-xs-7{margin-left:2.5rem !important}.mx-xs-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-xs-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-xs-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 20rem){.m-xs-8{margin:3rem !important}.mt-xs-8{margin-top:3rem !important}.mr-xs-8{margin-right:3rem !important}.mb-xs-8{margin-bottom:3rem !important}.ml-xs-8{margin-left:3rem !important}.mx-xs-8{margin-right:3rem !important;margin-left:3rem !important}.my-xs-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-xs-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 20rem){.m-xs-9{margin:3.5rem !important}.mt-xs-9{margin-top:3.5rem !important}.mr-xs-9{margin-right:3.5rem !important}.mb-xs-9{margin-bottom:3.5rem !important}.ml-xs-9{margin-left:3.5rem !important}.mx-xs-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-xs-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-xs-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 20rem){.m-xs-10{margin:4rem !important}.mt-xs-10{margin-top:4rem !important}.mr-xs-10{margin-right:4rem !important}.mb-xs-10{margin-bottom:4rem !important}.ml-xs-10{margin-left:4rem !important}.mx-xs-10{margin-right:4rem !important;margin-left:4rem !important}.my-xs-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-xs-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 31.25rem){.m-sm-0{margin:0 !important}.mt-sm-0{margin-top:0 !important}.mr-sm-0{margin-right:0 !important}.mb-sm-0{margin-bottom:0 !important}.ml-sm-0{margin-left:0 !important}.mx-sm-0{margin-right:0 !important;margin-left:0 !important}.my-sm-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-sm-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 31.25rem){.m-sm-1{margin:.25rem !important}.mt-sm-1{margin-top:.25rem !important}.mr-sm-1{margin-right:.25rem !important}.mb-sm-1{margin-bottom:.25rem !important}.ml-sm-1{margin-left:.25rem !important}.mx-sm-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-sm-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-sm-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 31.25rem){.m-sm-2{margin:.5rem !important}.mt-sm-2{margin-top:.5rem !important}.mr-sm-2{margin-right:.5rem !important}.mb-sm-2{margin-bottom:.5rem !important}.ml-sm-2{margin-left:.5rem !important}.mx-sm-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-sm-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-sm-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 31.25rem){.m-sm-3{margin:.75rem !important}.mt-sm-3{margin-top:.75rem !important}.mr-sm-3{margin-right:.75rem !important}.mb-sm-3{margin-bottom:.75rem !important}.ml-sm-3{margin-left:.75rem !important}.mx-sm-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-sm-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-sm-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 31.25rem){.m-sm-4{margin:1rem !important}.mt-sm-4{margin-top:1rem !important}.mr-sm-4{margin-right:1rem !important}.mb-sm-4{margin-bottom:1rem !important}.ml-sm-4{margin-left:1rem !important}.mx-sm-4{margin-right:1rem !important;margin-left:1rem !important}.my-sm-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-sm-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 31.25rem){.m-sm-5{margin:1.5rem !important}.mt-sm-5{margin-top:1.5rem !important}.mr-sm-5{margin-right:1.5rem !important}.mb-sm-5{margin-bottom:1.5rem !important}.ml-sm-5{margin-left:1.5rem !important}.mx-sm-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-sm-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-sm-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 31.25rem){.m-sm-6{margin:2rem !important}.mt-sm-6{margin-top:2rem !important}.mr-sm-6{margin-right:2rem !important}.mb-sm-6{margin-bottom:2rem !important}.ml-sm-6{margin-left:2rem !important}.mx-sm-6{margin-right:2rem !important;margin-left:2rem !important}.my-sm-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-sm-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 31.25rem){.m-sm-7{margin:2.5rem !important}.mt-sm-7{margin-top:2.5rem !important}.mr-sm-7{margin-right:2.5rem !important}.mb-sm-7{margin-bottom:2.5rem !important}.ml-sm-7{margin-left:2.5rem !important}.mx-sm-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-sm-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-sm-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 31.25rem){.m-sm-8{margin:3rem !important}.mt-sm-8{margin-top:3rem !important}.mr-sm-8{margin-right:3rem !important}.mb-sm-8{margin-bottom:3rem !important}.ml-sm-8{margin-left:3rem !important}.mx-sm-8{margin-right:3rem !important;margin-left:3rem !important}.my-sm-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-sm-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 31.25rem){.m-sm-9{margin:3.5rem !important}.mt-sm-9{margin-top:3.5rem !important}.mr-sm-9{margin-right:3.5rem !important}.mb-sm-9{margin-bottom:3.5rem !important}.ml-sm-9{margin-left:3.5rem !important}.mx-sm-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-sm-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-sm-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 31.25rem){.m-sm-10{margin:4rem !important}.mt-sm-10{margin-top:4rem !important}.mr-sm-10{margin-right:4rem !important}.mb-sm-10{margin-bottom:4rem !important}.ml-sm-10{margin-left:4rem !important}.mx-sm-10{margin-right:4rem !important;margin-left:4rem !important}.my-sm-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-sm-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 50rem){.m-md-0{margin:0 !important}.mt-md-0{margin-top:0 !important}.mr-md-0{margin-right:0 !important}.mb-md-0{margin-bottom:0 !important}.ml-md-0{margin-left:0 !important}.mx-md-0{margin-right:0 !important;margin-left:0 !important}.my-md-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-md-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 50rem){.m-md-1{margin:.25rem !important}.mt-md-1{margin-top:.25rem !important}.mr-md-1{margin-right:.25rem !important}.mb-md-1{margin-bottom:.25rem !important}.ml-md-1{margin-left:.25rem !important}.mx-md-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-md-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-md-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 50rem){.m-md-2{margin:.5rem !important}.mt-md-2{margin-top:.5rem !important}.mr-md-2{margin-right:.5rem !important}.mb-md-2{margin-bottom:.5rem !important}.ml-md-2{margin-left:.5rem !important}.mx-md-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-md-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-md-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 50rem){.m-md-3{margin:.75rem !important}.mt-md-3{margin-top:.75rem !important}.mr-md-3{margin-right:.75rem !important}.mb-md-3{margin-bottom:.75rem !important}.ml-md-3{margin-left:.75rem !important}.mx-md-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-md-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-md-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 50rem){.m-md-4{margin:1rem !important}.mt-md-4{margin-top:1rem !important}.mr-md-4{margin-right:1rem !important}.mb-md-4{margin-bottom:1rem !important}.ml-md-4{margin-left:1rem !important}.mx-md-4{margin-right:1rem !important;margin-left:1rem !important}.my-md-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-md-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 50rem){.m-md-5{margin:1.5rem !important}.mt-md-5{margin-top:1.5rem !important}.mr-md-5{margin-right:1.5rem !important}.mb-md-5{margin-bottom:1.5rem !important}.ml-md-5{margin-left:1.5rem !important}.mx-md-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-md-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-md-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 50rem){.m-md-6{margin:2rem !important}.mt-md-6{margin-top:2rem !important}.mr-md-6{margin-right:2rem !important}.mb-md-6{margin-bottom:2rem !important}.ml-md-6{margin-left:2rem !important}.mx-md-6{margin-right:2rem !important;margin-left:2rem !important}.my-md-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-md-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 50rem){.m-md-7{margin:2.5rem !important}.mt-md-7{margin-top:2.5rem !important}.mr-md-7{margin-right:2.5rem !important}.mb-md-7{margin-bottom:2.5rem !important}.ml-md-7{margin-left:2.5rem !important}.mx-md-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-md-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-md-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 50rem){.m-md-8{margin:3rem !important}.mt-md-8{margin-top:3rem !important}.mr-md-8{margin-right:3rem !important}.mb-md-8{margin-bottom:3rem !important}.ml-md-8{margin-left:3rem !important}.mx-md-8{margin-right:3rem !important;margin-left:3rem !important}.my-md-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-md-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 50rem){.m-md-9{margin:3.5rem !important}.mt-md-9{margin-top:3.5rem !important}.mr-md-9{margin-right:3.5rem !important}.mb-md-9{margin-bottom:3.5rem !important}.ml-md-9{margin-left:3.5rem !important}.mx-md-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-md-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-md-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 50rem){.m-md-10{margin:4rem !important}.mt-md-10{margin-top:4rem !important}.mr-md-10{margin-right:4rem !important}.mb-md-10{margin-bottom:4rem !important}.ml-md-10{margin-left:4rem !important}.mx-md-10{margin-right:4rem !important;margin-left:4rem !important}.my-md-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-md-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 66.5rem){.m-lg-0{margin:0 !important}.mt-lg-0{margin-top:0 !important}.mr-lg-0{margin-right:0 !important}.mb-lg-0{margin-bottom:0 !important}.ml-lg-0{margin-left:0 !important}.mx-lg-0{margin-right:0 !important;margin-left:0 !important}.my-lg-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-lg-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 66.5rem){.m-lg-1{margin:.25rem !important}.mt-lg-1{margin-top:.25rem !important}.mr-lg-1{margin-right:.25rem !important}.mb-lg-1{margin-bottom:.25rem !important}.ml-lg-1{margin-left:.25rem !important}.mx-lg-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-lg-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-lg-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 66.5rem){.m-lg-2{margin:.5rem !important}.mt-lg-2{margin-top:.5rem !important}.mr-lg-2{margin-right:.5rem !important}.mb-lg-2{margin-bottom:.5rem !important}.ml-lg-2{margin-left:.5rem !important}.mx-lg-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-lg-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-lg-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 66.5rem){.m-lg-3{margin:.75rem !important}.mt-lg-3{margin-top:.75rem !important}.mr-lg-3{margin-right:.75rem !important}.mb-lg-3{margin-bottom:.75rem !important}.ml-lg-3{margin-left:.75rem !important}.mx-lg-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-lg-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-lg-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 66.5rem){.m-lg-4{margin:1rem !important}.mt-lg-4{margin-top:1rem !important}.mr-lg-4{margin-right:1rem !important}.mb-lg-4{margin-bottom:1rem !important}.ml-lg-4{margin-left:1rem !important}.mx-lg-4{margin-right:1rem !important;margin-left:1rem !important}.my-lg-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-lg-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 66.5rem){.m-lg-5{margin:1.5rem !important}.mt-lg-5{margin-top:1.5rem !important}.mr-lg-5{margin-right:1.5rem !important}.mb-lg-5{margin-bottom:1.5rem !important}.ml-lg-5{margin-left:1.5rem !important}.mx-lg-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-lg-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-lg-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 66.5rem){.m-lg-6{margin:2rem !important}.mt-lg-6{margin-top:2rem !important}.mr-lg-6{margin-right:2rem !important}.mb-lg-6{margin-bottom:2rem !important}.ml-lg-6{margin-left:2rem !important}.mx-lg-6{margin-right:2rem !important;margin-left:2rem !important}.my-lg-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-lg-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 66.5rem){.m-lg-7{margin:2.5rem !important}.mt-lg-7{margin-top:2.5rem !important}.mr-lg-7{margin-right:2.5rem !important}.mb-lg-7{margin-bottom:2.5rem !important}.ml-lg-7{margin-left:2.5rem !important}.mx-lg-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-lg-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-lg-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 66.5rem){.m-lg-8{margin:3rem !important}.mt-lg-8{margin-top:3rem !important}.mr-lg-8{margin-right:3rem !important}.mb-lg-8{margin-bottom:3rem !important}.ml-lg-8{margin-left:3rem !important}.mx-lg-8{margin-right:3rem !important;margin-left:3rem !important}.my-lg-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-lg-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 66.5rem){.m-lg-9{margin:3.5rem !important}.mt-lg-9{margin-top:3.5rem !important}.mr-lg-9{margin-right:3.5rem !important}.mb-lg-9{margin-bottom:3.5rem !important}.ml-lg-9{margin-left:3.5rem !important}.mx-lg-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-lg-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-lg-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 66.5rem){.m-lg-10{margin:4rem !important}.mt-lg-10{margin-top:4rem !important}.mr-lg-10{margin-right:4rem !important}.mb-lg-10{margin-bottom:4rem !important}.ml-lg-10{margin-left:4rem !important}.mx-lg-10{margin-right:4rem !important;margin-left:4rem !important}.my-lg-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-lg-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 87.5rem){.m-xl-0{margin:0 !important}.mt-xl-0{margin-top:0 !important}.mr-xl-0{margin-right:0 !important}.mb-xl-0{margin-bottom:0 !important}.ml-xl-0{margin-left:0 !important}.mx-xl-0{margin-right:0 !important;margin-left:0 !important}.my-xl-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-xl-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 87.5rem){.m-xl-1{margin:.25rem !important}.mt-xl-1{margin-top:.25rem !important}.mr-xl-1{margin-right:.25rem !important}.mb-xl-1{margin-bottom:.25rem !important}.ml-xl-1{margin-left:.25rem !important}.mx-xl-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-xl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-xl-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 87.5rem){.m-xl-2{margin:.5rem !important}.mt-xl-2{margin-top:.5rem !important}.mr-xl-2{margin-right:.5rem !important}.mb-xl-2{margin-bottom:.5rem !important}.ml-xl-2{margin-left:.5rem !important}.mx-xl-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-xl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-xl-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 87.5rem){.m-xl-3{margin:.75rem !important}.mt-xl-3{margin-top:.75rem !important}.mr-xl-3{margin-right:.75rem !important}.mb-xl-3{margin-bottom:.75rem !important}.ml-xl-3{margin-left:.75rem !important}.mx-xl-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-xl-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-xl-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 87.5rem){.m-xl-4{margin:1rem !important}.mt-xl-4{margin-top:1rem !important}.mr-xl-4{margin-right:1rem !important}.mb-xl-4{margin-bottom:1rem !important}.ml-xl-4{margin-left:1rem !important}.mx-xl-4{margin-right:1rem !important;margin-left:1rem !important}.my-xl-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-xl-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 87.5rem){.m-xl-5{margin:1.5rem !important}.mt-xl-5{margin-top:1.5rem !important}.mr-xl-5{margin-right:1.5rem !important}.mb-xl-5{margin-bottom:1.5rem !important}.ml-xl-5{margin-left:1.5rem !important}.mx-xl-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-xl-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-xl-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 87.5rem){.m-xl-6{margin:2rem !important}.mt-xl-6{margin-top:2rem !important}.mr-xl-6{margin-right:2rem !important}.mb-xl-6{margin-bottom:2rem !important}.ml-xl-6{margin-left:2rem !important}.mx-xl-6{margin-right:2rem !important;margin-left:2rem !important}.my-xl-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-xl-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 87.5rem){.m-xl-7{margin:2.5rem !important}.mt-xl-7{margin-top:2.5rem !important}.mr-xl-7{margin-right:2.5rem !important}.mb-xl-7{margin-bottom:2.5rem !important}.ml-xl-7{margin-left:2.5rem !important}.mx-xl-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-xl-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-xl-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 87.5rem){.m-xl-8{margin:3rem !important}.mt-xl-8{margin-top:3rem !important}.mr-xl-8{margin-right:3rem !important}.mb-xl-8{margin-bottom:3rem !important}.ml-xl-8{margin-left:3rem !important}.mx-xl-8{margin-right:3rem !important;margin-left:3rem !important}.my-xl-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-xl-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 87.5rem){.m-xl-9{margin:3.5rem !important}.mt-xl-9{margin-top:3.5rem !important}.mr-xl-9{margin-right:3.5rem !important}.mb-xl-9{margin-bottom:3.5rem !important}.ml-xl-9{margin-left:3.5rem !important}.mx-xl-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-xl-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-xl-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 87.5rem){.m-xl-10{margin:4rem !important}.mt-xl-10{margin-top:4rem !important}.mr-xl-10{margin-right:4rem !important}.mb-xl-10{margin-bottom:4rem !important}.ml-xl-10{margin-left:4rem !important}.mx-xl-10{margin-right:4rem !important;margin-left:4rem !important}.my-xl-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-xl-10{margin-right:-4rem !important;margin-left:-4rem !important}}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-right:0 !important;padding-left:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-right:1rem !important;padding-left:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:2rem !important}.pt-6{padding-top:2rem !important}.pr-6{padding-right:2rem !important}.pb-6{padding-bottom:2rem !important}.pl-6{padding-left:2rem !important}.px-6{padding-right:2rem !important;padding-left:2rem !important}.py-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-7{padding:2.5rem !important}.pt-7{padding-top:2.5rem !important}.pr-7{padding-right:2.5rem !important}.pb-7{padding-bottom:2.5rem !important}.pl-7{padding-left:2.5rem !important}.px-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-8{padding:3rem !important}.pt-8{padding-top:3rem !important}.pr-8{padding-right:3rem !important}.pb-8{padding-bottom:3rem !important}.pl-8{padding-left:3rem !important}.px-8{padding-right:3rem !important;padding-left:3rem !important}.py-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-9{padding:3.5rem !important}.pt-9{padding-top:3.5rem !important}.pr-9{padding-right:3.5rem !important}.pb-9{padding-bottom:3.5rem !important}.pl-9{padding-left:3.5rem !important}.px-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-10{padding:4rem !important}.pt-10{padding-top:4rem !important}.pr-10{padding-right:4rem !important}.pb-10{padding-bottom:4rem !important}.pl-10{padding-left:4rem !important}.px-10{padding-right:4rem !important;padding-left:4rem !important}.py-10{padding-top:4rem !important;padding-bottom:4rem !important}@media (min-width: 20rem){.p-xs-0{padding:0 !important}.pt-xs-0{padding-top:0 !important}.pr-xs-0{padding-right:0 !important}.pb-xs-0{padding-bottom:0 !important}.pl-xs-0{padding-left:0 !important}.px-xs-0{padding-right:0 !important;padding-left:0 !important}.py-xs-0{padding-top:0 !important;padding-bottom:0 !important}.p-xs-1{padding:.25rem !important}.pt-xs-1{padding-top:.25rem !important}.pr-xs-1{padding-right:.25rem !important}.pb-xs-1{padding-bottom:.25rem !important}.pl-xs-1{padding-left:.25rem !important}.px-xs-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-xs-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-xs-2{padding:.5rem !important}.pt-xs-2{padding-top:.5rem !important}.pr-xs-2{padding-right:.5rem !important}.pb-xs-2{padding-bottom:.5rem !important}.pl-xs-2{padding-left:.5rem !important}.px-xs-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-xs-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-xs-3{padding:.75rem !important}.pt-xs-3{padding-top:.75rem !important}.pr-xs-3{padding-right:.75rem !important}.pb-xs-3{padding-bottom:.75rem !important}.pl-xs-3{padding-left:.75rem !important}.px-xs-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-xs-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-xs-4{padding:1rem !important}.pt-xs-4{padding-top:1rem !important}.pr-xs-4{padding-right:1rem !important}.pb-xs-4{padding-bottom:1rem !important}.pl-xs-4{padding-left:1rem !important}.px-xs-4{padding-right:1rem !important;padding-left:1rem !important}.py-xs-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-xs-5{padding:1.5rem !important}.pt-xs-5{padding-top:1.5rem !important}.pr-xs-5{padding-right:1.5rem !important}.pb-xs-5{padding-bottom:1.5rem !important}.pl-xs-5{padding-left:1.5rem !important}.px-xs-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-xs-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-xs-6{padding:2rem !important}.pt-xs-6{padding-top:2rem !important}.pr-xs-6{padding-right:2rem !important}.pb-xs-6{padding-bottom:2rem !important}.pl-xs-6{padding-left:2rem !important}.px-xs-6{padding-right:2rem !important;padding-left:2rem !important}.py-xs-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-xs-7{padding:2.5rem !important}.pt-xs-7{padding-top:2.5rem !important}.pr-xs-7{padding-right:2.5rem !important}.pb-xs-7{padding-bottom:2.5rem !important}.pl-xs-7{padding-left:2.5rem !important}.px-xs-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-xs-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-xs-8{padding:3rem !important}.pt-xs-8{padding-top:3rem !important}.pr-xs-8{padding-right:3rem !important}.pb-xs-8{padding-bottom:3rem !important}.pl-xs-8{padding-left:3rem !important}.px-xs-8{padding-right:3rem !important;padding-left:3rem !important}.py-xs-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-xs-9{padding:3.5rem !important}.pt-xs-9{padding-top:3.5rem !important}.pr-xs-9{padding-right:3.5rem !important}.pb-xs-9{padding-bottom:3.5rem !important}.pl-xs-9{padding-left:3.5rem !important}.px-xs-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-xs-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-xs-10{padding:4rem !important}.pt-xs-10{padding-top:4rem !important}.pr-xs-10{padding-right:4rem !important}.pb-xs-10{padding-bottom:4rem !important}.pl-xs-10{padding-left:4rem !important}.px-xs-10{padding-right:4rem !important;padding-left:4rem !important}.py-xs-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 31.25rem){.p-sm-0{padding:0 !important}.pt-sm-0{padding-top:0 !important}.pr-sm-0{padding-right:0 !important}.pb-sm-0{padding-bottom:0 !important}.pl-sm-0{padding-left:0 !important}.px-sm-0{padding-right:0 !important;padding-left:0 !important}.py-sm-0{padding-top:0 !important;padding-bottom:0 !important}.p-sm-1{padding:.25rem !important}.pt-sm-1{padding-top:.25rem !important}.pr-sm-1{padding-right:.25rem !important}.pb-sm-1{padding-bottom:.25rem !important}.pl-sm-1{padding-left:.25rem !important}.px-sm-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-sm-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-sm-2{padding:.5rem !important}.pt-sm-2{padding-top:.5rem !important}.pr-sm-2{padding-right:.5rem !important}.pb-sm-2{padding-bottom:.5rem !important}.pl-sm-2{padding-left:.5rem !important}.px-sm-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-sm-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-sm-3{padding:.75rem !important}.pt-sm-3{padding-top:.75rem !important}.pr-sm-3{padding-right:.75rem !important}.pb-sm-3{padding-bottom:.75rem !important}.pl-sm-3{padding-left:.75rem !important}.px-sm-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-sm-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-sm-4{padding:1rem !important}.pt-sm-4{padding-top:1rem !important}.pr-sm-4{padding-right:1rem !important}.pb-sm-4{padding-bottom:1rem !important}.pl-sm-4{padding-left:1rem !important}.px-sm-4{padding-right:1rem !important;padding-left:1rem !important}.py-sm-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-sm-5{padding:1.5rem !important}.pt-sm-5{padding-top:1.5rem !important}.pr-sm-5{padding-right:1.5rem !important}.pb-sm-5{padding-bottom:1.5rem !important}.pl-sm-5{padding-left:1.5rem !important}.px-sm-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-sm-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-sm-6{padding:2rem !important}.pt-sm-6{padding-top:2rem !important}.pr-sm-6{padding-right:2rem !important}.pb-sm-6{padding-bottom:2rem !important}.pl-sm-6{padding-left:2rem !important}.px-sm-6{padding-right:2rem !important;padding-left:2rem !important}.py-sm-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-sm-7{padding:2.5rem !important}.pt-sm-7{padding-top:2.5rem !important}.pr-sm-7{padding-right:2.5rem !important}.pb-sm-7{padding-bottom:2.5rem !important}.pl-sm-7{padding-left:2.5rem !important}.px-sm-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-sm-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-sm-8{padding:3rem !important}.pt-sm-8{padding-top:3rem !important}.pr-sm-8{padding-right:3rem !important}.pb-sm-8{padding-bottom:3rem !important}.pl-sm-8{padding-left:3rem !important}.px-sm-8{padding-right:3rem !important;padding-left:3rem !important}.py-sm-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-sm-9{padding:3.5rem !important}.pt-sm-9{padding-top:3.5rem !important}.pr-sm-9{padding-right:3.5rem !important}.pb-sm-9{padding-bottom:3.5rem !important}.pl-sm-9{padding-left:3.5rem !important}.px-sm-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-sm-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-sm-10{padding:4rem !important}.pt-sm-10{padding-top:4rem !important}.pr-sm-10{padding-right:4rem !important}.pb-sm-10{padding-bottom:4rem !important}.pl-sm-10{padding-left:4rem !important}.px-sm-10{padding-right:4rem !important;padding-left:4rem !important}.py-sm-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 50rem){.p-md-0{padding:0 !important}.pt-md-0{padding-top:0 !important}.pr-md-0{padding-right:0 !important}.pb-md-0{padding-bottom:0 !important}.pl-md-0{padding-left:0 !important}.px-md-0{padding-right:0 !important;padding-left:0 !important}.py-md-0{padding-top:0 !important;padding-bottom:0 !important}.p-md-1{padding:.25rem !important}.pt-md-1{padding-top:.25rem !important}.pr-md-1{padding-right:.25rem !important}.pb-md-1{padding-bottom:.25rem !important}.pl-md-1{padding-left:.25rem !important}.px-md-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-md-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-md-2{padding:.5rem !important}.pt-md-2{padding-top:.5rem !important}.pr-md-2{padding-right:.5rem !important}.pb-md-2{padding-bottom:.5rem !important}.pl-md-2{padding-left:.5rem !important}.px-md-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-md-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-md-3{padding:.75rem !important}.pt-md-3{padding-top:.75rem !important}.pr-md-3{padding-right:.75rem !important}.pb-md-3{padding-bottom:.75rem !important}.pl-md-3{padding-left:.75rem !important}.px-md-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-md-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-md-4{padding:1rem !important}.pt-md-4{padding-top:1rem !important}.pr-md-4{padding-right:1rem !important}.pb-md-4{padding-bottom:1rem !important}.pl-md-4{padding-left:1rem !important}.px-md-4{padding-right:1rem !important;padding-left:1rem !important}.py-md-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-md-5{padding:1.5rem !important}.pt-md-5{padding-top:1.5rem !important}.pr-md-5{padding-right:1.5rem !important}.pb-md-5{padding-bottom:1.5rem !important}.pl-md-5{padding-left:1.5rem !important}.px-md-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-md-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-md-6{padding:2rem !important}.pt-md-6{padding-top:2rem !important}.pr-md-6{padding-right:2rem !important}.pb-md-6{padding-bottom:2rem !important}.pl-md-6{padding-left:2rem !important}.px-md-6{padding-right:2rem !important;padding-left:2rem !important}.py-md-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-md-7{padding:2.5rem !important}.pt-md-7{padding-top:2.5rem !important}.pr-md-7{padding-right:2.5rem !important}.pb-md-7{padding-bottom:2.5rem !important}.pl-md-7{padding-left:2.5rem !important}.px-md-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-md-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-md-8{padding:3rem !important}.pt-md-8{padding-top:3rem !important}.pr-md-8{padding-right:3rem !important}.pb-md-8{padding-bottom:3rem !important}.pl-md-8{padding-left:3rem !important}.px-md-8{padding-right:3rem !important;padding-left:3rem !important}.py-md-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-md-9{padding:3.5rem !important}.pt-md-9{padding-top:3.5rem !important}.pr-md-9{padding-right:3.5rem !important}.pb-md-9{padding-bottom:3.5rem !important}.pl-md-9{padding-left:3.5rem !important}.px-md-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-md-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-md-10{padding:4rem !important}.pt-md-10{padding-top:4rem !important}.pr-md-10{padding-right:4rem !important}.pb-md-10{padding-bottom:4rem !important}.pl-md-10{padding-left:4rem !important}.px-md-10{padding-right:4rem !important;padding-left:4rem !important}.py-md-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 66.5rem){.p-lg-0{padding:0 !important}.pt-lg-0{padding-top:0 !important}.pr-lg-0{padding-right:0 !important}.pb-lg-0{padding-bottom:0 !important}.pl-lg-0{padding-left:0 !important}.px-lg-0{padding-right:0 !important;padding-left:0 !important}.py-lg-0{padding-top:0 !important;padding-bottom:0 !important}.p-lg-1{padding:.25rem !important}.pt-lg-1{padding-top:.25rem !important}.pr-lg-1{padding-right:.25rem !important}.pb-lg-1{padding-bottom:.25rem !important}.pl-lg-1{padding-left:.25rem !important}.px-lg-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-lg-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-lg-2{padding:.5rem !important}.pt-lg-2{padding-top:.5rem !important}.pr-lg-2{padding-right:.5rem !important}.pb-lg-2{padding-bottom:.5rem !important}.pl-lg-2{padding-left:.5rem !important}.px-lg-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-lg-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-lg-3{padding:.75rem !important}.pt-lg-3{padding-top:.75rem !important}.pr-lg-3{padding-right:.75rem !important}.pb-lg-3{padding-bottom:.75rem !important}.pl-lg-3{padding-left:.75rem !important}.px-lg-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-lg-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-lg-4{padding:1rem !important}.pt-lg-4{padding-top:1rem !important}.pr-lg-4{padding-right:1rem !important}.pb-lg-4{padding-bottom:1rem !important}.pl-lg-4{padding-left:1rem !important}.px-lg-4{padding-right:1rem !important;padding-left:1rem !important}.py-lg-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-lg-5{padding:1.5rem !important}.pt-lg-5{padding-top:1.5rem !important}.pr-lg-5{padding-right:1.5rem !important}.pb-lg-5{padding-bottom:1.5rem !important}.pl-lg-5{padding-left:1.5rem !important}.px-lg-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-lg-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-lg-6{padding:2rem !important}.pt-lg-6{padding-top:2rem !important}.pr-lg-6{padding-right:2rem !important}.pb-lg-6{padding-bottom:2rem !important}.pl-lg-6{padding-left:2rem !important}.px-lg-6{padding-right:2rem !important;padding-left:2rem !important}.py-lg-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-lg-7{padding:2.5rem !important}.pt-lg-7{padding-top:2.5rem !important}.pr-lg-7{padding-right:2.5rem !important}.pb-lg-7{padding-bottom:2.5rem !important}.pl-lg-7{padding-left:2.5rem !important}.px-lg-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-lg-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-lg-8{padding:3rem !important}.pt-lg-8{padding-top:3rem !important}.pr-lg-8{padding-right:3rem !important}.pb-lg-8{padding-bottom:3rem !important}.pl-lg-8{padding-left:3rem !important}.px-lg-8{padding-right:3rem !important;padding-left:3rem !important}.py-lg-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-lg-9{padding:3.5rem !important}.pt-lg-9{padding-top:3.5rem !important}.pr-lg-9{padding-right:3.5rem !important}.pb-lg-9{padding-bottom:3.5rem !important}.pl-lg-9{padding-left:3.5rem !important}.px-lg-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-lg-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-lg-10{padding:4rem !important}.pt-lg-10{padding-top:4rem !important}.pr-lg-10{padding-right:4rem !important}.pb-lg-10{padding-bottom:4rem !important}.pl-lg-10{padding-left:4rem !important}.px-lg-10{padding-right:4rem !important;padding-left:4rem !important}.py-lg-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 87.5rem){.p-xl-0{padding:0 !important}.pt-xl-0{padding-top:0 !important}.pr-xl-0{padding-right:0 !important}.pb-xl-0{padding-bottom:0 !important}.pl-xl-0{padding-left:0 !important}.px-xl-0{padding-right:0 !important;padding-left:0 !important}.py-xl-0{padding-top:0 !important;padding-bottom:0 !important}.p-xl-1{padding:.25rem !important}.pt-xl-1{padding-top:.25rem !important}.pr-xl-1{padding-right:.25rem !important}.pb-xl-1{padding-bottom:.25rem !important}.pl-xl-1{padding-left:.25rem !important}.px-xl-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-xl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-xl-2{padding:.5rem !important}.pt-xl-2{padding-top:.5rem !important}.pr-xl-2{padding-right:.5rem !important}.pb-xl-2{padding-bottom:.5rem !important}.pl-xl-2{padding-left:.5rem !important}.px-xl-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-xl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-xl-3{padding:.75rem !important}.pt-xl-3{padding-top:.75rem !important}.pr-xl-3{padding-right:.75rem !important}.pb-xl-3{padding-bottom:.75rem !important}.pl-xl-3{padding-left:.75rem !important}.px-xl-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-xl-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-xl-4{padding:1rem !important}.pt-xl-4{padding-top:1rem !important}.pr-xl-4{padding-right:1rem !important}.pb-xl-4{padding-bottom:1rem !important}.pl-xl-4{padding-left:1rem !important}.px-xl-4{padding-right:1rem !important;padding-left:1rem !important}.py-xl-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-xl-5{padding:1.5rem !important}.pt-xl-5{padding-top:1.5rem !important}.pr-xl-5{padding-right:1.5rem !important}.pb-xl-5{padding-bottom:1.5rem !important}.pl-xl-5{padding-left:1.5rem !important}.px-xl-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-xl-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-xl-6{padding:2rem !important}.pt-xl-6{padding-top:2rem !important}.pr-xl-6{padding-right:2rem !important}.pb-xl-6{padding-bottom:2rem !important}.pl-xl-6{padding-left:2rem !important}.px-xl-6{padding-right:2rem !important;padding-left:2rem !important}.py-xl-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-xl-7{padding:2.5rem !important}.pt-xl-7{padding-top:2.5rem !important}.pr-xl-7{padding-right:2.5rem !important}.pb-xl-7{padding-bottom:2.5rem !important}.pl-xl-7{padding-left:2.5rem !important}.px-xl-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-xl-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-xl-8{padding:3rem !important}.pt-xl-8{padding-top:3rem !important}.pr-xl-8{padding-right:3rem !important}.pb-xl-8{padding-bottom:3rem !important}.pl-xl-8{padding-left:3rem !important}.px-xl-8{padding-right:3rem !important;padding-left:3rem !important}.py-xl-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-xl-9{padding:3.5rem !important}.pt-xl-9{padding-top:3.5rem !important}.pr-xl-9{padding-right:3.5rem !important}.pb-xl-9{padding-bottom:3.5rem !important}.pl-xl-9{padding-left:3.5rem !important}.px-xl-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-xl-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-xl-10{padding:4rem !important}.pt-xl-10{padding-top:4rem !important}.pr-xl-10{padding-right:4rem !important}.pb-xl-10{padding-bottom:4rem !important}.pl-xl-10{padding-left:4rem !important}.px-xl-10{padding-right:4rem !important;padding-left:4rem !important}.py-xl-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media print{.site-footer,.site-button,#edit-this-page,#back-to-top,.site-nav,.main-header{display:none !important}.side-bar{width:100%;height:auto;border-right:0 !important}.site-header{border-bottom:1px solid #44434d}.site-title{font-size:16px !important;font-weight:700 !important}.text-small{font-size:8pt !important}pre.highlight{border:1px solid #44434d}.main{max-width:none;margin-left:0}}a.skip-to-main{left:-999px;position:absolute;top:auto;width:1px;height:1px;overflow:hidden;z-index:-999}a.skip-to-main:focus,a.skip-to-main:active{color:#2c84fa;background-color:#27262b;left:auto;top:auto;width:30%;height:auto;overflow:auto;margin:10px 35%;padding:5px;border-radius:15px;border:4px solid #264caf;text-align:center;font-size:1.2em;z-index:999}div.opaque{background-color:#27262b} diff --git a/assets/css/just-the-docs-default.css b/assets/css/just-the-docs-default.css new file mode 100644 index 0000000000..96c47a3a02 --- /dev/null +++ b/assets/css/just-the-docs-default.css @@ -0,0 +1 @@ +.highlight .c{color:#586e75}.highlight .err{color:#93a1a1}.highlight .g{color:#93a1a1}.highlight .k{color:#859900}.highlight .l{color:#93a1a1}.highlight .n{color:#93a1a1}.highlight .o{color:#859900}.highlight .x{color:#cb4b16}.highlight .p{color:#93a1a1}.highlight .cm{color:#586e75}.highlight .cp{color:#859900}.highlight .c1{color:#586e75}.highlight .cs{color:#859900}.highlight .gd{color:#2aa198}.highlight .ge{font-style:italic;color:#93a1a1}.highlight .gr{color:#dc322f}.highlight .gh{color:#cb4b16}.highlight .gi{color:#859900}.highlight .go{color:#93a1a1}.highlight .gp{color:#93a1a1}.highlight .gs{font-weight:bold;color:#93a1a1}.highlight .gu{color:#cb4b16}.highlight .gt{color:#93a1a1}.highlight .kc{color:#cb4b16}.highlight .kd{color:#268bd2}.highlight .kn{color:#859900}.highlight .kp{color:#859900}.highlight .kr{color:#268bd2}.highlight .kt{color:#dc322f}.highlight .ld{color:#93a1a1}.highlight .m{color:#2aa198}.highlight .s{color:#2aa198}.highlight .na{color:#555}.highlight .nb{color:#b58900}.highlight .nc{color:#268bd2}.highlight .no{color:#cb4b16}.highlight .nd{color:#268bd2}.highlight .ni{color:#cb4b16}.highlight .ne{color:#cb4b16}.highlight .nf{color:#268bd2}.highlight .nl{color:#555}.highlight .nn{color:#93a1a1}.highlight .nx{color:#555}.highlight .py{color:#93a1a1}.highlight .nt{color:#268bd2}.highlight .nv{color:#268bd2}.highlight .ow{color:#859900}.highlight .w{color:#93a1a1}.highlight .mf{color:#2aa198}.highlight .mh{color:#2aa198}.highlight .mi{color:#2aa198}.highlight .mo{color:#2aa198}.highlight .sb{color:#586e75}.highlight .sc{color:#2aa198}.highlight .sd{color:#93a1a1}.highlight .s2{color:#2aa198}.highlight .se{color:#cb4b16}.highlight .sh{color:#93a1a1}.highlight .si{color:#2aa198}.highlight .sx{color:#2aa198}.highlight .sr{color:#dc322f}.highlight .s1{color:#2aa198}.highlight .ss{color:#2aa198}.highlight .bp{color:#268bd2}.highlight .vc{color:#268bd2}.highlight .vg{color:#268bd2}.highlight .vi{color:#268bd2}.highlight .il{color:#2aa198}/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}main{display:block}h1{font-size:2em;margin:0.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace, monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace, monospace;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}button,[type="button"],[type="reset"],[type="submit"]{-webkit-appearance:button}button::-moz-focus-inner,[type="button"]::-moz-focus-inner,[type="reset"]::-moz-focus-inner,[type="submit"]::-moz-focus-inner{border-style:none;padding:0}button:-moz-focusring,[type="button"]:-moz-focusring,[type="reset"]:-moz-focusring,[type="submit"]:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:0.35em 0.75em 0.625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type="checkbox"],[type="radio"]{box-sizing:border-box;padding:0}[type="number"]::-webkit-inner-spin-button,[type="number"]::-webkit-outer-spin-button{height:auto}[type="search"]{-webkit-appearance:textfield;outline-offset:-2px}[type="search"]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}template{display:none}[hidden]{display:none}*{box-sizing:border-box}::selection{color:#fff;background:#53a3da}html{font-size:14px !important;scroll-behavior:smooth}@media (min-width: 31.25rem){html{font-size:16px !important}}body{font-family:system-ui,-apple-system,blinkmacsystemfont,"Segoe UI",roboto,"Helvetica Neue",arial,sans-serif;font-size:inherit;line-height:1.4;color:#5c5962;background-color:#fff;overflow-wrap:break-word}ol,ul,dl,pre,address,blockquote,table,div,hr,form,fieldset,noscript .table-wrapper{margin-top:0}h1,h2,h3,h4,h5,h6,#toctitle{margin-top:0;margin-bottom:1em;font-weight:500;line-height:1.25;color:#27262b}p{margin-top:1em;margin-bottom:1em}a{color:#53a3da;text-decoration:none}a:not([class]){text-decoration:underline;text-decoration-color:#eeebee;text-underline-offset:2px}a:not([class]):hover{text-decoration-color:rgba(83,163,218,0.45)}code{font-family:"SFMono-Regular",menlo,consolas,monospace;font-size:0.75em;line-height:1.4}figure,pre{margin:0}li{margin:0.25em 0}img{max-width:100%;height:auto}hr{height:1px;padding:0;margin:2rem 0;background-color:#eeebee;border:0}blockquote{margin:10px 0;margin-block-start:0;margin-inline-start:0;padding-left:15px;border-left:3px solid #eeebee}.side-bar{z-index:0;display:flex;flex-wrap:wrap;background-color:#f5f6fa}@media (min-width: 50rem){.side-bar{flex-flow:column nowrap;position:fixed;width:248px;height:100%;border-right:1px solid #eeebee;align-items:flex-end}}@media (min-width: 66.5rem){.side-bar{width:calc((100% - 1064px) / 2 + 264px);min-width:264px}}@media (min-width: 50rem){.main{position:relative;max-width:800px;margin-left:248px}}@media (min-width: 66.5rem){.main{margin-left:Max(264px, calc((100% - 1064px) / 2 + 264px))}}.main-content-wrap{padding-right:1rem;padding-left:1rem;padding-top:1rem;padding-bottom:1rem}@media (min-width: 50rem){.main-content-wrap{padding-right:2rem;padding-left:2rem}}@media (min-width: 50rem){.main-content-wrap{padding-top:2rem;padding-bottom:2rem}}.main-header{z-index:0;display:none;background-color:#f5f6fa}@media (min-width: 50rem){.main-header{display:flex;justify-content:space-between;height:60px;background-color:#fff;border-bottom:1px solid #eeebee}}.main-header.nav-open{display:block}@media (min-width: 50rem){.main-header.nav-open{display:flex}}.site-nav,.site-header,.site-footer{width:100%}@media (min-width: 66.5rem){.site-nav,.site-header,.site-footer{width:264px}}.site-nav{display:none}.site-nav.nav-open{display:block}@media (min-width: 50rem){.site-nav{display:block;padding-top:3rem;padding-bottom:1rem;overflow-y:auto;flex:1 1 auto}}.site-header{display:flex;min-height:60px;align-items:center}@media (min-width: 50rem){.site-header{height:60px;max-height:60px;border-bottom:1px solid #eeebee}}.site-title{padding-right:1rem;padding-left:1rem;flex-grow:1;display:flex;height:100%;align-items:center;padding-top:.75rem;padding-bottom:.75rem;color:#27262b;font-size:18px !important}@media (min-width: 50rem){.site-title{padding-right:2rem;padding-left:2rem}}@media (min-width: 31.25rem){.site-title{font-size:24px !important;line-height:1.25}}@media (min-width: 50rem){.site-title{padding-top:.5rem;padding-bottom:.5rem}}.site-button{display:flex;height:100%;padding:1rem;align-items:center}@media (min-width: 50rem){.site-header .site-button{display:none}}.site-title:hover{background-image:linear-gradient(-90deg, #ebedf5 0%, rgba(235,237,245,0.8) 80%, rgba(235,237,245,0) 100%)}.site-button:hover{background-image:linear-gradient(-90deg, #ebedf5 0%, rgba(235,237,245,0.8) 100%)}body{position:relative;padding-bottom:4rem;overflow-y:scroll}@media (min-width: 50rem){body{position:static;padding-bottom:0}}.site-footer{padding-right:1rem;padding-left:1rem;position:absolute;bottom:0;left:0;padding-top:1rem;padding-bottom:1rem;color:#959396;font-size:11px !important}@media (min-width: 50rem){.site-footer{padding-right:2rem;padding-left:2rem}}@media (min-width: 31.25rem){.site-footer{font-size:12px !important}}@media (min-width: 50rem){.site-footer{position:static;justify-self:end}}.icon{width:1.5rem;height:1.5rem;color:#53a3da}.main-content{line-height:1.6}.main-content ol,.main-content ul,.main-content dl,.main-content pre,.main-content address,.main-content blockquote,.main-content .table-wrapper{margin-top:0.5em}.main-content a{overflow:hidden;text-overflow:ellipsis}.main-content ul,.main-content ol{padding-left:1.5em}.main-content li .highlight{margin-top:.25rem}.main-content ol{list-style-type:none;counter-reset:step-counter}.main-content ol>li{position:relative}.main-content ol>li::before{position:absolute;top:0.2em;left:-1.6em;color:#959396;content:counter(step-counter);counter-increment:step-counter;font-size:12px !important}@media (min-width: 31.25rem){.main-content ol>li::before{font-size:14px !important}}@media (min-width: 31.25rem){.main-content ol>li::before{top:0.11em}}.main-content ol>li ol{counter-reset:sub-counter}.main-content ol>li ol>li::before{content:counter(sub-counter,lower-alpha);counter-increment:sub-counter}.main-content ul{list-style:none}.main-content ul>li::before{position:absolute;margin-left:-1.4em;color:#959396;content:"•"}.main-content .task-list-item::before{content:""}.main-content .task-list-item-checkbox{margin-right:0.6em;margin-left:-1.4em}.main-content hr+*{margin-top:0}.main-content h1:first-of-type{margin-top:0.5em}.main-content dl{display:grid;grid-template:auto / 10em 1fr}.main-content dt,.main-content dd{margin:0.25em 0}.main-content dt{grid-column:1;font-weight:500;text-align:right}.main-content dt::after{content:":"}.main-content dd{grid-column:2;margin-bottom:0;margin-left:1em}.main-content dd blockquote:first-child,.main-content dd div:first-child,.main-content dd dl:first-child,.main-content dd dt:first-child,.main-content dd h1:first-child,.main-content dd h2:first-child,.main-content dd h3:first-child,.main-content dd h4:first-child,.main-content dd h5:first-child,.main-content dd h6:first-child,.main-content dd li:first-child,.main-content dd ol:first-child,.main-content dd p:first-child,.main-content dd pre:first-child,.main-content dd table:first-child,.main-content dd ul:first-child,.main-content dd .table-wrapper:first-child{margin-top:0}.main-content dd dl:first-child dt:first-child,.main-content dd dl:first-child dd:nth-child(2),.main-content ol dl:first-child dt:first-child,.main-content ol dl:first-child dd:nth-child(2),.main-content ul dl:first-child dt:first-child,.main-content ul dl:first-child dd:nth-child(2){margin-top:0}.main-content .anchor-heading{position:absolute;right:-1rem;width:1.5rem;height:100%;padding-right:.25rem;padding-left:.25rem;overflow:visible}@media (min-width: 50rem){.main-content .anchor-heading{right:auto;left:-1.5rem}}.main-content .anchor-heading svg{display:inline-block;width:100%;height:100%;color:#53a3da;visibility:hidden}.main-content .anchor-heading:hover svg,.main-content .anchor-heading:focus svg,.main-content h1:hover>.anchor-heading svg,.main-content h2:hover>.anchor-heading svg,.main-content h3:hover>.anchor-heading svg,.main-content h4:hover>.anchor-heading svg,.main-content h5:hover>.anchor-heading svg,.main-content h6:hover>.anchor-heading svg{visibility:visible}.main-content summary{cursor:pointer}.main-content h1,.main-content h2,.main-content h3,.main-content h4,.main-content h5,.main-content h6,.main-content #toctitle{position:relative;margin-top:1.5em;margin-bottom:0.25em}.main-content h1+table,.main-content h1+.table-wrapper,.main-content h1+.code-example,.main-content h1+.highlighter-rouge,.main-content h1+.sectionbody .listingblock,.main-content h2+table,.main-content h2+.table-wrapper,.main-content h2+.code-example,.main-content h2+.highlighter-rouge,.main-content h2+.sectionbody .listingblock,.main-content h3+table,.main-content h3+.table-wrapper,.main-content h3+.code-example,.main-content h3+.highlighter-rouge,.main-content h3+.sectionbody .listingblock,.main-content h4+table,.main-content h4+.table-wrapper,.main-content h4+.code-example,.main-content h4+.highlighter-rouge,.main-content h4+.sectionbody .listingblock,.main-content h5+table,.main-content h5+.table-wrapper,.main-content h5+.code-example,.main-content h5+.highlighter-rouge,.main-content h5+.sectionbody .listingblock,.main-content h6+table,.main-content h6+.table-wrapper,.main-content h6+.code-example,.main-content h6+.highlighter-rouge,.main-content h6+.sectionbody .listingblock,.main-content #toctitle+table,.main-content #toctitle+.table-wrapper,.main-content #toctitle+.code-example,.main-content #toctitle+.highlighter-rouge,.main-content #toctitle+.sectionbody .listingblock{margin-top:1em}.main-content h1+p:not(.label),.main-content h2+p:not(.label),.main-content h3+p:not(.label),.main-content h4+p:not(.label),.main-content h5+p:not(.label),.main-content h6+p:not(.label),.main-content #toctitle+p:not(.label){margin-top:0}.main-content>h1:first-child,.main-content>h2:first-child,.main-content>h3:first-child,.main-content>h4:first-child,.main-content>h5:first-child,.main-content>h6:first-child,.main-content>.sect1:first-child>h2,.main-content>.sect2:first-child>h3,.main-content>.sect3:first-child>h4,.main-content>.sect4:first-child>h5,.main-content>.sect5:first-child>h6{margin-top:.5rem}.nav-list{padding:0;margin-top:0;margin-bottom:0;list-style:none}.nav-list .nav-list-item{font-size:14px !important;position:relative;margin:0}@media (min-width: 31.25rem){.nav-list .nav-list-item{font-size:16px !important}}@media (min-width: 50rem){.nav-list .nav-list-item{font-size:12px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.nav-list .nav-list-item{font-size:14px !important}}.nav-list .nav-list-item .nav-list-link{display:block;min-height:3rem;padding-top:.25rem;padding-bottom:.25rem;line-height:2.5rem;padding-right:3rem;padding-left:1rem}@media (min-width: 50rem){.nav-list .nav-list-item .nav-list-link{min-height:2rem;line-height:1.5rem;padding-right:2rem;padding-left:2rem}}.nav-list .nav-list-item .nav-list-link.external>svg{width:1rem;height:1rem;vertical-align:text-bottom}.nav-list .nav-list-item .nav-list-link.active{font-weight:600;text-decoration:none}.nav-list .nav-list-item .nav-list-link:hover,.nav-list .nav-list-item .nav-list-link.active{background-image:linear-gradient(-90deg, #ebedf5 0%, rgba(235,237,245,0.8) 80%, rgba(235,237,245,0) 100%)}.nav-list .nav-list-item .nav-list-expander{position:absolute;right:0;width:3rem;height:3rem;padding:.75rem;color:#53a3da}@media (min-width: 50rem){.nav-list .nav-list-item .nav-list-expander{width:2rem;height:2rem;padding:.5rem}}.nav-list .nav-list-item .nav-list-expander:hover{background-image:linear-gradient(-90deg, #ebedf5 0%, rgba(235,237,245,0.8) 100%)}.nav-list .nav-list-item .nav-list-expander svg{transform:rotate(90deg)}.nav-list .nav-list-item>.nav-list{display:none;padding-left:.75rem;list-style:none}.nav-list .nav-list-item>.nav-list .nav-list-item{position:relative}.nav-list .nav-list-item>.nav-list .nav-list-item .nav-list-link{color:#5c5962}.nav-list .nav-list-item>.nav-list .nav-list-item .nav-list-expander{color:#5c5962}.nav-list .nav-list-item.active>.nav-list-expander svg{transform:rotate(-90deg)}.nav-list .nav-list-item.active>.nav-list{display:block}.nav-category{padding:.5rem 1rem;font-weight:600;text-align:start;text-transform:uppercase;border-bottom:1px solid #eeebee;font-size:11px !important}@media (min-width: 31.25rem){.nav-category{font-size:12px !important}}@media (min-width: 50rem){.nav-category{padding:.5rem 2rem;margin-top:1rem;text-align:start}.nav-category:first-child{margin-top:0}}.nav-list.nav-category-list>.nav-list-item{margin:0}.nav-list.nav-category-list>.nav-list-item>.nav-list{padding:0}.nav-list.nav-category-list>.nav-list-item>.nav-list>.nav-list-item>.nav-list-link{color:#53a3da}.nav-list.nav-category-list>.nav-list-item>.nav-list>.nav-list-item>.nav-list-expander{color:#53a3da}.aux-nav{height:100%;overflow-x:auto;font-size:11px !important}@media (min-width: 31.25rem){.aux-nav{font-size:12px !important}}.aux-nav .aux-nav-list{display:flex;height:100%;padding:0;margin:0;list-style:none}.aux-nav .aux-nav-list-item{display:inline-block;height:100%;padding:0;margin:0}@media (min-width: 50rem){.aux-nav{padding-right:1rem}}@media (min-width: 50rem){.breadcrumb-nav{margin-top:-1rem}}.breadcrumb-nav-list{padding-left:0;margin-bottom:.75rem;list-style:none}.breadcrumb-nav-list-item{display:table-cell;font-size:11px !important}@media (min-width: 31.25rem){.breadcrumb-nav-list-item{font-size:12px !important}}.breadcrumb-nav-list-item::before{display:none}.breadcrumb-nav-list-item::after{display:inline-block;margin-right:.5rem;margin-left:.5rem;color:#959396;content:"/"}.breadcrumb-nav-list-item:last-child::after{content:""}h1,.text-alpha{font-size:32px !important;line-height:1.25;font-weight:300}@media (min-width: 31.25rem){h1,.text-alpha{font-size:36px !important}}h2,.text-beta,#toctitle{font-size:18px !important}@media (min-width: 31.25rem){h2,.text-beta,#toctitle{font-size:24px !important;line-height:1.25}}h3,.text-gamma{font-size:16px !important}@media (min-width: 31.25rem){h3,.text-gamma{font-size:18px !important}}h4,.text-delta{font-size:11px !important;font-weight:400;text-transform:uppercase;letter-spacing:0.1em}@media (min-width: 31.25rem){h4,.text-delta{font-size:12px !important}}h4 code{text-transform:none}h5,.text-epsilon{font-size:12px !important}@media (min-width: 31.25rem){h5,.text-epsilon{font-size:14px !important}}h6,.text-zeta{font-size:11px !important}@media (min-width: 31.25rem){h6,.text-zeta{font-size:12px !important}}.text-small{font-size:11px !important}@media (min-width: 31.25rem){.text-small{font-size:12px !important}}.text-mono{font-family:"SFMono-Regular",menlo,consolas,monospace !important}.text-left{text-align:left !important}.text-center{text-align:center !important}.text-right{text-align:right !important}.label,.label-blue{display:inline-block;padding:0.16em 0.56em;margin-right:.5rem;margin-left:.5rem;color:#fff;text-transform:uppercase;vertical-align:middle;background-color:#2869e6;font-size:11px !important;border-radius:12px}@media (min-width: 31.25rem){.label,.label-blue{font-size:12px !important}}.label-green{background-color:#009c7b}.label-purple{background-color:#5e41d0}.label-red{background-color:#e94c4c}.label-yellow{color:#44434d;background-color:#f7d12e}.btn{display:inline-block;box-sizing:border-box;padding:0.3em 1em;margin:0;font-family:inherit;font-size:inherit;font-weight:500;line-height:1.5;color:#53a3da;text-decoration:none;vertical-align:baseline;cursor:pointer;background-color:#f7f7f7;border-width:0;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);appearance:none}.btn:focus{text-decoration:none;outline:none;box-shadow:0 0 0 3px rgba(0,0,255,0.25)}.btn:focus:hover,.btn.selected:focus{box-shadow:0 0 0 3px rgba(0,0,255,0.25)}.btn:hover,.btn.zeroclipboard-is-hover{color:#4b9fd8}.btn:hover,.btn:active,.btn.zeroclipboard-is-hover,.btn.zeroclipboard-is-active{text-decoration:none;background-color:#f4f4f4}.btn:active,.btn.selected,.btn.zeroclipboard-is-active{background-color:#efefef;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn.selected:hover{background-color:#cfcfcf}.btn:disabled,.btn:disabled:hover,.btn.disabled,.btn.disabled:hover{color:rgba(102,102,102,0.5);cursor:default;background-color:rgba(229,229,229,0.5);background-image:none;box-shadow:none}.btn-outline{color:#53a3da;background:transparent;box-shadow:inset 0 0 0 2px #e6e1e8}.btn-outline:hover,.btn-outline:active,.btn-outline.zeroclipboard-is-hover,.btn-outline.zeroclipboard-is-active{color:#429ad6;text-decoration:none;background-color:transparent;box-shadow:inset 0 0 0 3px #e6e1e8}.btn-outline:focus{text-decoration:none;outline:none;box-shadow:inset 0 0 0 2px #5c5962,0 0 0 3px rgba(0,0,255,0.25)}.btn-outline:focus:hover,.btn-outline.selected:focus{box-shadow:inset 0 0 0 2px #5c5962}.btn-primary{color:#fff;background-color:#5739ce;background-image:linear-gradient(#6f55d5, #5739ce);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-primary:hover,.btn-primary.zeroclipboard-is-hover{color:#fff;background-color:#5132cb;background-image:linear-gradient(#6549d2,#5132cb)}.btn-primary:active,.btn-primary.selected,.btn-primary.zeroclipboard-is-active{background-color:#4f31c6;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-primary.selected:hover{background-color:#472cb2}.btn-purple{color:#fff;background-color:#5739ce;background-image:linear-gradient(#6f55d5, #5739ce);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-purple:hover,.btn-purple.zeroclipboard-is-hover{color:#fff;background-color:#5132cb;background-image:linear-gradient(#6549d2,#5132cb)}.btn-purple:active,.btn-purple.selected,.btn-purple.zeroclipboard-is-active{background-color:#4f31c6;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-purple.selected:hover{background-color:#472cb2}.btn-blue{color:#fff;background-color:#227efa;background-image:linear-gradient(#4593fb, #227efa);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-blue:hover,.btn-blue.zeroclipboard-is-hover{color:#fff;background-color:#1878fa;background-image:linear-gradient(#368afa,#1878fa)}.btn-blue:active,.btn-blue.selected,.btn-blue.zeroclipboard-is-active{background-color:#1375f9;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-blue.selected:hover{background-color:#0669ed}.btn-green{color:#fff;background-color:#10ac7d;background-image:linear-gradient(#13cc95, #10ac7d);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-green:hover,.btn-green.zeroclipboard-is-hover{color:#fff;background-color:#0fa276;background-image:linear-gradient(#12be8b,#0fa276)}.btn-green:active,.btn-green.selected,.btn-green.zeroclipboard-is-active{background-color:#0f9e73;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-green.selected:hover{background-color:#0d8662}.search{position:relative;z-index:2;flex-grow:1;height:4rem;padding:.5rem;transition:padding linear 200ms}@media (min-width: 50rem){.search{position:relative !important;width:auto !important;height:100% !important;padding:0;transition:none}}.search-input-wrap{position:relative;z-index:1;height:3rem;overflow:hidden;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);transition:height linear 200ms}@media (min-width: 50rem){.search-input-wrap{position:absolute;width:100%;max-width:536px;height:100% !important;border-radius:0;box-shadow:none;transition:width ease 400ms}}.search-input{position:absolute;width:100%;height:100%;padding:.5rem 1rem .5rem 2.5rem;font-size:16px;color:#5c5962;background-color:#fff;border-top:0;border-right:0;border-bottom:0;border-left:0;border-radius:0}@media (min-width: 50rem){.search-input{padding:.5rem 1rem .5rem 3.5rem;font-size:14px;background-color:#fff;transition:padding-left linear 200ms}}.search-input:focus{outline:0}.search-input:focus+.search-label .search-icon{color:#53a3da}.search-label{position:absolute;display:flex;height:100%;padding-left:1rem}@media (min-width: 50rem){.search-label{padding-left:2rem;transition:padding-left linear 200ms}}.search-label .search-icon{width:1.2rem;height:1.2rem;align-self:center;color:#959396}.search-results{position:absolute;left:0;display:none;width:100%;max-height:calc(100% - 4rem);overflow-y:auto;background-color:#fff;border-bottom-right-radius:4px;border-bottom-left-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}@media (min-width: 50rem){.search-results{top:100%;width:536px;max-height:calc(100vh - 200%) !important}}.search-results-list{padding-left:0;margin-bottom:.25rem;list-style:none;font-size:14px !important}@media (min-width: 31.25rem){.search-results-list{font-size:16px !important}}@media (min-width: 50rem){.search-results-list{font-size:12px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.search-results-list{font-size:14px !important}}.search-results-list-item{padding:0;margin:0}.search-result{display:block;padding:.25rem .75rem}.search-result:hover,.search-result.active{background-color:#ebedf5}.search-result-title{display:block;padding-top:.5rem;padding-bottom:.5rem}@media (min-width: 31.25rem){.search-result-title{display:inline-block;width:40%;padding-right:.5rem;vertical-align:top}}.search-result-doc{display:flex;align-items:center;word-wrap:break-word}.search-result-doc.search-result-doc-parent{opacity:0.5;font-size:12px !important}@media (min-width: 31.25rem){.search-result-doc.search-result-doc-parent{font-size:14px !important}}@media (min-width: 50rem){.search-result-doc.search-result-doc-parent{font-size:11px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.search-result-doc.search-result-doc-parent{font-size:12px !important}}.search-result-doc .search-result-icon{width:1rem;height:1rem;margin-right:.5rem;color:#53a3da;flex-shrink:0}.search-result-doc .search-result-doc-title{overflow:auto}.search-result-section{margin-left:1.5rem;word-wrap:break-word}.search-result-rel-url{display:block;margin-left:1.5rem;overflow:hidden;color:#959396;text-overflow:ellipsis;white-space:nowrap;font-size:9px !important}@media (min-width: 31.25rem){.search-result-rel-url{font-size:10px !important}}.search-result-previews{display:block;padding-top:.5rem;padding-bottom:.5rem;padding-left:1rem;margin-left:.5rem;color:#959396;word-wrap:break-word;border-left:1px solid;border-left-color:#eeebee;font-size:11px !important}@media (min-width: 31.25rem){.search-result-previews{font-size:12px !important}}@media (min-width: 31.25rem){.search-result-previews{display:inline-block;width:60%;padding-left:.5rem;margin-left:0;vertical-align:top}}.search-result-preview+.search-result-preview{margin-top:.25rem}.search-result-highlight{font-weight:bold}.search-no-result{padding:.5rem .75rem;font-size:12px !important}@media (min-width: 31.25rem){.search-no-result{font-size:14px !important}}.search-button{position:fixed;right:1rem;bottom:1rem;display:flex;width:3.5rem;height:3.5rem;background-color:#fff;border:1px solid rgba(83,163,218,0.3);border-radius:1.75rem;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);align-items:center;justify-content:center}.search-overlay{position:fixed;top:0;left:0;z-index:1;width:0;height:0;background-color:rgba(0,0,0,0.3);opacity:0;transition:opacity ease 400ms,width 0s 400ms,height 0s 400ms}.search-active .search{position:fixed;top:0;left:0;width:100%;height:100%;padding:0}.search-active .search-input-wrap{height:4rem;border-radius:0}@media (min-width: 50rem){.search-active .search-input-wrap{width:536px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}}.search-active .search-input{background-color:#fff}@media (min-width: 50rem){.search-active .search-input{padding-left:2.3rem}}@media (min-width: 50rem){.search-active .search-label{padding-left:0.6rem}}.search-active .search-results{display:block}.search-active .search-overlay{width:100%;height:100%;opacity:1;transition:opacity ease 400ms,width 0s,height 0s}@media (min-width: 50rem){.search-active .main{position:fixed;right:0;left:0}}.search-active .main-header{padding-top:4rem}@media (min-width: 50rem){.search-active .main-header{padding-top:0}}.table-wrapper{display:block;width:100%;max-width:100%;margin-bottom:1.5rem;overflow-x:auto;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}table{display:table;min-width:100%;border-collapse:separate}th,td{font-size:12px !important;min-width:120px;padding:.5rem .75rem;background-color:#fff;border-bottom:1px solid rgba(238,235,238,0.5);border-left:1px solid #eeebee}@media (min-width: 31.25rem){th,td{font-size:14px !important}}th:first-of-type,td:first-of-type{border-left:0}tbody tr:last-of-type th,tbody tr:last-of-type td{border-bottom:0}tbody tr:last-of-type td{padding-bottom:.75rem}thead th{border-bottom:1px solid #eeebee}:not(pre,figure)>code{padding:0.2em 0.15em;font-weight:400;background-color:#f5f6fa;border:1px solid #eeebee;border-radius:4px}a:visited code{border-color:#eeebee}div.highlighter-rouge,div.listingblock>div.content,figure.highlight{margin-top:0;margin-bottom:.75rem;background-color:#f5f6fa;border-radius:4px;box-shadow:none;-webkit-overflow-scrolling:touch;position:relative;padding:0}div.highlighter-rouge>button,div.listingblock>div.content>button,figure.highlight>button{width:.75rem;opacity:0;position:absolute;top:0;right:0;border:.75rem solid #f5f6fa;background-color:#f5f6fa;color:#5c5962;box-sizing:content-box}div.highlighter-rouge>button svg,div.listingblock>div.content>button svg,figure.highlight>button svg{fill:#5c5962}div.highlighter-rouge>button:active,div.listingblock>div.content>button:active,figure.highlight>button:active{text-decoration:none;outline:none;opacity:1}div.highlighter-rouge>button:focus,div.listingblock>div.content>button:focus,figure.highlight>button:focus{opacity:1}div.highlighter-rouge:hover>button,div.listingblock>div.content:hover>button,figure.highlight:hover>button{cursor:copy;opacity:1}div.highlighter-rouge div.highlight{overflow-x:auto;padding:.75rem;margin:0;border:0}div.highlighter-rouge pre.highlight,div.highlighter-rouge code{padding:0;margin:0;border:0}div.listingblock{margin-top:0;margin-bottom:.75rem}div.listingblock div.content{overflow-x:auto;padding:.75rem;margin:0;border:0}div.listingblock div.content>pre,div.listingblock code{padding:0;margin:0;border:0}figure.highlight pre,figure.highlight :not(pre)>code{overflow-x:auto;padding:.75rem;margin:0;border:0}.highlight .table-wrapper{padding:.75rem 0;margin:0;border:0;box-shadow:none}.highlight .table-wrapper td,.highlight .table-wrapper pre{font-size:11px !important;min-width:0;padding:0;background-color:#f5f6fa;border:0}@media (min-width: 31.25rem){.highlight .table-wrapper td,.highlight .table-wrapper pre{font-size:12px !important}}.highlight .table-wrapper td.gl{width:1em;padding-right:.75rem;padding-left:.75rem}.highlight .table-wrapper pre{margin:0;line-height:2}.code-example,.listingblock>.title{padding:.75rem;margin-bottom:.75rem;overflow:auto;border:1px solid #eeebee;border-radius:4px}.code-example+.highlighter-rouge,.code-example+.sectionbody .listingblock,.code-example+.content,.code-example+figure.highlight,.listingblock>.title+.highlighter-rouge,.listingblock>.title+.sectionbody .listingblock,.listingblock>.title+.content,.listingblock>.title+figure.highlight{position:relative;margin-top:-1rem;border-right:1px solid #eeebee;border-bottom:1px solid #eeebee;border-left:1px solid #eeebee;border-top-left-radius:0;border-top-right-radius:0}code.language-mermaid{padding:0;background-color:inherit;border:0}.highlight,pre.highlight{background:#f5f6fa;color:#5c5962}.highlight pre{background:#f5f6fa}.text-grey-dk-000{color:#959396 !important}.text-grey-dk-100{color:#5c5962 !important}.text-grey-dk-200{color:#44434d !important}.text-grey-dk-250{color:#302d36 !important}.text-grey-dk-300{color:#27262b !important}.text-grey-lt-000{color:#f5f6fa !important}.text-grey-lt-100{color:#eeebee !important}.text-grey-lt-200{color:#ecebed !important}.text-grey-lt-300{color:#e6e1e8 !important}.text-blue-000{color:#2c84fa !important}.text-blue-100{color:#2869e6 !important}.text-blue-200{color:#264caf !important}.text-blue-300{color:#183385 !important}.text-green-000{color:#41d693 !important}.text-green-100{color:#11b584 !important}.text-green-200{color:#009c7b !important}.text-green-300{color:#026e57 !important}.text-purple-000{color:#7253ed !important}.text-purple-100{color:#5e41d0 !important}.text-purple-200{color:#4e26af !important}.text-purple-300{color:#381885 !important}.text-yellow-000{color:#ffeb82 !important}.text-yellow-100{color:#fadf50 !important}.text-yellow-200{color:#f7d12e !important}.text-yellow-300{color:#e7af06 !important}.text-red-000{color:#f77e7e !important}.text-red-100{color:#f96e65 !important}.text-red-200{color:#e94c4c !important}.text-red-300{color:#dd2e2e !important}.bg-grey-dk-000{background-color:#959396 !important}.bg-grey-dk-100{background-color:#5c5962 !important}.bg-grey-dk-200{background-color:#44434d !important}.bg-grey-dk-250{background-color:#302d36 !important}.bg-grey-dk-300{background-color:#27262b !important}.bg-grey-lt-000{background-color:#f5f6fa !important}.bg-grey-lt-100{background-color:#eeebee !important}.bg-grey-lt-200{background-color:#ecebed !important}.bg-grey-lt-300{background-color:#e6e1e8 !important}.bg-blue-000{background-color:#2c84fa !important}.bg-blue-100{background-color:#2869e6 !important}.bg-blue-200{background-color:#264caf !important}.bg-blue-300{background-color:#183385 !important}.bg-green-000{background-color:#41d693 !important}.bg-green-100{background-color:#11b584 !important}.bg-green-200{background-color:#009c7b !important}.bg-green-300{background-color:#026e57 !important}.bg-purple-000{background-color:#7253ed !important}.bg-purple-100{background-color:#5e41d0 !important}.bg-purple-200{background-color:#4e26af !important}.bg-purple-300{background-color:#381885 !important}.bg-yellow-000{background-color:#ffeb82 !important}.bg-yellow-100{background-color:#fadf50 !important}.bg-yellow-200{background-color:#f7d12e !important}.bg-yellow-300{background-color:#e7af06 !important}.bg-red-000{background-color:#f77e7e !important}.bg-red-100{background-color:#f96e65 !important}.bg-red-200{background-color:#e94c4c !important}.bg-red-300{background-color:#dd2e2e !important}.d-block{display:block !important}.d-flex{display:flex !important}.d-inline{display:inline !important}.d-inline-block{display:inline-block !important}.d-none{display:none !important}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}.float-left{float:left !important}.float-right{float:right !important}.flex-justify-start{justify-content:flex-start !important}.flex-justify-end{justify-content:flex-end !important}.flex-justify-between{justify-content:space-between !important}.flex-justify-around{justify-content:space-around !important}.v-align-baseline{vertical-align:baseline !important}.v-align-bottom{vertical-align:bottom !important}.v-align-middle{vertical-align:middle !important}.v-align-text-bottom{vertical-align:text-bottom !important}.v-align-text-top{vertical-align:text-top !important}.v-align-top{vertical-align:top !important}.fs-1{font-size:9px !important}@media (min-width: 31.25rem){.fs-1{font-size:10px !important}}.fs-2{font-size:11px !important}@media (min-width: 31.25rem){.fs-2{font-size:12px !important}}.fs-3{font-size:12px !important}@media (min-width: 31.25rem){.fs-3{font-size:14px !important}}.fs-4{font-size:14px !important}@media (min-width: 31.25rem){.fs-4{font-size:16px !important}}.fs-5{font-size:16px !important}@media (min-width: 31.25rem){.fs-5{font-size:18px !important}}.fs-6{font-size:18px !important}@media (min-width: 31.25rem){.fs-6{font-size:24px !important;line-height:1.25}}.fs-7{font-size:24px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-7{font-size:32px !important}}.fs-8{font-size:32px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-8{font-size:36px !important}}.fs-9{font-size:36px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-9{font-size:42px !important}}.fs-10{font-size:42px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-10{font-size:48px !important}}.fw-300{font-weight:300 !important}.fw-400{font-weight:400 !important}.fw-500{font-weight:500 !important}.fw-700{font-weight:700 !important}.lh-0{line-height:0 !important}.lh-default{line-height:1.4}.lh-tight{line-height:1.25}.ls-5{letter-spacing:0.05em !important}.ls-10{letter-spacing:0.1em !important}.ls-0{letter-spacing:0 !important}.text-uppercase{text-transform:uppercase !important}.list-style-none{padding:0 !important;margin:0 !important;list-style:none !important}.list-style-none li::before{display:none !important}.mx-auto{margin-right:auto !important;margin-left:auto !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-right:0 !important;margin-left:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-0{margin-right:-0 !important;margin-left:-0 !important}.mx-0-auto{margin-right:auto !important;margin-left:auto !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-1{margin-right:-.25rem !important;margin-left:-.25rem !important}.mx-1-auto{margin-right:auto !important;margin-left:auto !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-2{margin-right:-.5rem !important;margin-left:-.5rem !important}.mx-2-auto{margin-right:auto !important;margin-left:auto !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-3{margin-right:-.75rem !important;margin-left:-.75rem !important}.mx-3-auto{margin-right:auto !important;margin-left:auto !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-right:1rem !important;margin-left:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-4{margin-right:-1rem !important;margin-left:-1rem !important}.mx-4-auto{margin-right:auto !important;margin-left:auto !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}.mx-5-auto{margin-right:auto !important;margin-left:auto !important}.m-6{margin:2rem !important}.mt-6{margin-top:2rem !important}.mr-6{margin-right:2rem !important}.mb-6{margin-bottom:2rem !important}.ml-6{margin-left:2rem !important}.mx-6{margin-right:2rem !important;margin-left:2rem !important}.my-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-6{margin-right:-2rem !important;margin-left:-2rem !important}.mx-6-auto{margin-right:auto !important;margin-left:auto !important}.m-7{margin:2.5rem !important}.mt-7{margin-top:2.5rem !important}.mr-7{margin-right:2.5rem !important}.mb-7{margin-bottom:2.5rem !important}.ml-7{margin-left:2.5rem !important}.mx-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}.mx-7-auto{margin-right:auto !important;margin-left:auto !important}.m-8{margin:3rem !important}.mt-8{margin-top:3rem !important}.mr-8{margin-right:3rem !important}.mb-8{margin-bottom:3rem !important}.ml-8{margin-left:3rem !important}.mx-8{margin-right:3rem !important;margin-left:3rem !important}.my-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-8{margin-right:-3rem !important;margin-left:-3rem !important}.mx-8-auto{margin-right:auto !important;margin-left:auto !important}.m-9{margin:3.5rem !important}.mt-9{margin-top:3.5rem !important}.mr-9{margin-right:3.5rem !important}.mb-9{margin-bottom:3.5rem !important}.ml-9{margin-left:3.5rem !important}.mx-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}.mx-9-auto{margin-right:auto !important;margin-left:auto !important}.m-10{margin:4rem !important}.mt-10{margin-top:4rem !important}.mr-10{margin-right:4rem !important}.mb-10{margin-bottom:4rem !important}.ml-10{margin-left:4rem !important}.mx-10{margin-right:4rem !important;margin-left:4rem !important}.my-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-10{margin-right:-4rem !important;margin-left:-4rem !important}.mx-10-auto{margin-right:auto !important;margin-left:auto !important}@media (min-width: 20rem){.m-xs-0{margin:0 !important}.mt-xs-0{margin-top:0 !important}.mr-xs-0{margin-right:0 !important}.mb-xs-0{margin-bottom:0 !important}.ml-xs-0{margin-left:0 !important}.mx-xs-0{margin-right:0 !important;margin-left:0 !important}.my-xs-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-xs-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 20rem){.m-xs-1{margin:.25rem !important}.mt-xs-1{margin-top:.25rem !important}.mr-xs-1{margin-right:.25rem !important}.mb-xs-1{margin-bottom:.25rem !important}.ml-xs-1{margin-left:.25rem !important}.mx-xs-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-xs-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-xs-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 20rem){.m-xs-2{margin:.5rem !important}.mt-xs-2{margin-top:.5rem !important}.mr-xs-2{margin-right:.5rem !important}.mb-xs-2{margin-bottom:.5rem !important}.ml-xs-2{margin-left:.5rem !important}.mx-xs-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-xs-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-xs-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 20rem){.m-xs-3{margin:.75rem !important}.mt-xs-3{margin-top:.75rem !important}.mr-xs-3{margin-right:.75rem !important}.mb-xs-3{margin-bottom:.75rem !important}.ml-xs-3{margin-left:.75rem !important}.mx-xs-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-xs-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-xs-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 20rem){.m-xs-4{margin:1rem !important}.mt-xs-4{margin-top:1rem !important}.mr-xs-4{margin-right:1rem !important}.mb-xs-4{margin-bottom:1rem !important}.ml-xs-4{margin-left:1rem !important}.mx-xs-4{margin-right:1rem !important;margin-left:1rem !important}.my-xs-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-xs-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 20rem){.m-xs-5{margin:1.5rem !important}.mt-xs-5{margin-top:1.5rem !important}.mr-xs-5{margin-right:1.5rem !important}.mb-xs-5{margin-bottom:1.5rem !important}.ml-xs-5{margin-left:1.5rem !important}.mx-xs-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-xs-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-xs-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 20rem){.m-xs-6{margin:2rem !important}.mt-xs-6{margin-top:2rem !important}.mr-xs-6{margin-right:2rem !important}.mb-xs-6{margin-bottom:2rem !important}.ml-xs-6{margin-left:2rem !important}.mx-xs-6{margin-right:2rem !important;margin-left:2rem !important}.my-xs-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-xs-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 20rem){.m-xs-7{margin:2.5rem !important}.mt-xs-7{margin-top:2.5rem !important}.mr-xs-7{margin-right:2.5rem !important}.mb-xs-7{margin-bottom:2.5rem !important}.ml-xs-7{margin-left:2.5rem !important}.mx-xs-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-xs-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-xs-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 20rem){.m-xs-8{margin:3rem !important}.mt-xs-8{margin-top:3rem !important}.mr-xs-8{margin-right:3rem !important}.mb-xs-8{margin-bottom:3rem !important}.ml-xs-8{margin-left:3rem !important}.mx-xs-8{margin-right:3rem !important;margin-left:3rem !important}.my-xs-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-xs-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 20rem){.m-xs-9{margin:3.5rem !important}.mt-xs-9{margin-top:3.5rem !important}.mr-xs-9{margin-right:3.5rem !important}.mb-xs-9{margin-bottom:3.5rem !important}.ml-xs-9{margin-left:3.5rem !important}.mx-xs-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-xs-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-xs-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 20rem){.m-xs-10{margin:4rem !important}.mt-xs-10{margin-top:4rem !important}.mr-xs-10{margin-right:4rem !important}.mb-xs-10{margin-bottom:4rem !important}.ml-xs-10{margin-left:4rem !important}.mx-xs-10{margin-right:4rem !important;margin-left:4rem !important}.my-xs-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-xs-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 31.25rem){.m-sm-0{margin:0 !important}.mt-sm-0{margin-top:0 !important}.mr-sm-0{margin-right:0 !important}.mb-sm-0{margin-bottom:0 !important}.ml-sm-0{margin-left:0 !important}.mx-sm-0{margin-right:0 !important;margin-left:0 !important}.my-sm-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-sm-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 31.25rem){.m-sm-1{margin:.25rem !important}.mt-sm-1{margin-top:.25rem !important}.mr-sm-1{margin-right:.25rem !important}.mb-sm-1{margin-bottom:.25rem !important}.ml-sm-1{margin-left:.25rem !important}.mx-sm-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-sm-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-sm-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 31.25rem){.m-sm-2{margin:.5rem !important}.mt-sm-2{margin-top:.5rem !important}.mr-sm-2{margin-right:.5rem !important}.mb-sm-2{margin-bottom:.5rem !important}.ml-sm-2{margin-left:.5rem !important}.mx-sm-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-sm-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-sm-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 31.25rem){.m-sm-3{margin:.75rem !important}.mt-sm-3{margin-top:.75rem !important}.mr-sm-3{margin-right:.75rem !important}.mb-sm-3{margin-bottom:.75rem !important}.ml-sm-3{margin-left:.75rem !important}.mx-sm-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-sm-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-sm-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 31.25rem){.m-sm-4{margin:1rem !important}.mt-sm-4{margin-top:1rem !important}.mr-sm-4{margin-right:1rem !important}.mb-sm-4{margin-bottom:1rem !important}.ml-sm-4{margin-left:1rem !important}.mx-sm-4{margin-right:1rem !important;margin-left:1rem !important}.my-sm-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-sm-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 31.25rem){.m-sm-5{margin:1.5rem !important}.mt-sm-5{margin-top:1.5rem !important}.mr-sm-5{margin-right:1.5rem !important}.mb-sm-5{margin-bottom:1.5rem !important}.ml-sm-5{margin-left:1.5rem !important}.mx-sm-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-sm-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-sm-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 31.25rem){.m-sm-6{margin:2rem !important}.mt-sm-6{margin-top:2rem !important}.mr-sm-6{margin-right:2rem !important}.mb-sm-6{margin-bottom:2rem !important}.ml-sm-6{margin-left:2rem !important}.mx-sm-6{margin-right:2rem !important;margin-left:2rem !important}.my-sm-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-sm-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 31.25rem){.m-sm-7{margin:2.5rem !important}.mt-sm-7{margin-top:2.5rem !important}.mr-sm-7{margin-right:2.5rem !important}.mb-sm-7{margin-bottom:2.5rem !important}.ml-sm-7{margin-left:2.5rem !important}.mx-sm-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-sm-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-sm-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 31.25rem){.m-sm-8{margin:3rem !important}.mt-sm-8{margin-top:3rem !important}.mr-sm-8{margin-right:3rem !important}.mb-sm-8{margin-bottom:3rem !important}.ml-sm-8{margin-left:3rem !important}.mx-sm-8{margin-right:3rem !important;margin-left:3rem !important}.my-sm-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-sm-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 31.25rem){.m-sm-9{margin:3.5rem !important}.mt-sm-9{margin-top:3.5rem !important}.mr-sm-9{margin-right:3.5rem !important}.mb-sm-9{margin-bottom:3.5rem !important}.ml-sm-9{margin-left:3.5rem !important}.mx-sm-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-sm-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-sm-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 31.25rem){.m-sm-10{margin:4rem !important}.mt-sm-10{margin-top:4rem !important}.mr-sm-10{margin-right:4rem !important}.mb-sm-10{margin-bottom:4rem !important}.ml-sm-10{margin-left:4rem !important}.mx-sm-10{margin-right:4rem !important;margin-left:4rem !important}.my-sm-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-sm-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 50rem){.m-md-0{margin:0 !important}.mt-md-0{margin-top:0 !important}.mr-md-0{margin-right:0 !important}.mb-md-0{margin-bottom:0 !important}.ml-md-0{margin-left:0 !important}.mx-md-0{margin-right:0 !important;margin-left:0 !important}.my-md-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-md-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 50rem){.m-md-1{margin:.25rem !important}.mt-md-1{margin-top:.25rem !important}.mr-md-1{margin-right:.25rem !important}.mb-md-1{margin-bottom:.25rem !important}.ml-md-1{margin-left:.25rem !important}.mx-md-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-md-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-md-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 50rem){.m-md-2{margin:.5rem !important}.mt-md-2{margin-top:.5rem !important}.mr-md-2{margin-right:.5rem !important}.mb-md-2{margin-bottom:.5rem !important}.ml-md-2{margin-left:.5rem !important}.mx-md-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-md-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-md-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 50rem){.m-md-3{margin:.75rem !important}.mt-md-3{margin-top:.75rem !important}.mr-md-3{margin-right:.75rem !important}.mb-md-3{margin-bottom:.75rem !important}.ml-md-3{margin-left:.75rem !important}.mx-md-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-md-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-md-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 50rem){.m-md-4{margin:1rem !important}.mt-md-4{margin-top:1rem !important}.mr-md-4{margin-right:1rem !important}.mb-md-4{margin-bottom:1rem !important}.ml-md-4{margin-left:1rem !important}.mx-md-4{margin-right:1rem !important;margin-left:1rem !important}.my-md-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-md-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 50rem){.m-md-5{margin:1.5rem !important}.mt-md-5{margin-top:1.5rem !important}.mr-md-5{margin-right:1.5rem !important}.mb-md-5{margin-bottom:1.5rem !important}.ml-md-5{margin-left:1.5rem !important}.mx-md-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-md-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-md-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 50rem){.m-md-6{margin:2rem !important}.mt-md-6{margin-top:2rem !important}.mr-md-6{margin-right:2rem !important}.mb-md-6{margin-bottom:2rem !important}.ml-md-6{margin-left:2rem !important}.mx-md-6{margin-right:2rem !important;margin-left:2rem !important}.my-md-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-md-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 50rem){.m-md-7{margin:2.5rem !important}.mt-md-7{margin-top:2.5rem !important}.mr-md-7{margin-right:2.5rem !important}.mb-md-7{margin-bottom:2.5rem !important}.ml-md-7{margin-left:2.5rem !important}.mx-md-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-md-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-md-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 50rem){.m-md-8{margin:3rem !important}.mt-md-8{margin-top:3rem !important}.mr-md-8{margin-right:3rem !important}.mb-md-8{margin-bottom:3rem !important}.ml-md-8{margin-left:3rem !important}.mx-md-8{margin-right:3rem !important;margin-left:3rem !important}.my-md-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-md-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 50rem){.m-md-9{margin:3.5rem !important}.mt-md-9{margin-top:3.5rem !important}.mr-md-9{margin-right:3.5rem !important}.mb-md-9{margin-bottom:3.5rem !important}.ml-md-9{margin-left:3.5rem !important}.mx-md-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-md-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-md-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 50rem){.m-md-10{margin:4rem !important}.mt-md-10{margin-top:4rem !important}.mr-md-10{margin-right:4rem !important}.mb-md-10{margin-bottom:4rem !important}.ml-md-10{margin-left:4rem !important}.mx-md-10{margin-right:4rem !important;margin-left:4rem !important}.my-md-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-md-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 66.5rem){.m-lg-0{margin:0 !important}.mt-lg-0{margin-top:0 !important}.mr-lg-0{margin-right:0 !important}.mb-lg-0{margin-bottom:0 !important}.ml-lg-0{margin-left:0 !important}.mx-lg-0{margin-right:0 !important;margin-left:0 !important}.my-lg-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-lg-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 66.5rem){.m-lg-1{margin:.25rem !important}.mt-lg-1{margin-top:.25rem !important}.mr-lg-1{margin-right:.25rem !important}.mb-lg-1{margin-bottom:.25rem !important}.ml-lg-1{margin-left:.25rem !important}.mx-lg-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-lg-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-lg-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 66.5rem){.m-lg-2{margin:.5rem !important}.mt-lg-2{margin-top:.5rem !important}.mr-lg-2{margin-right:.5rem !important}.mb-lg-2{margin-bottom:.5rem !important}.ml-lg-2{margin-left:.5rem !important}.mx-lg-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-lg-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-lg-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 66.5rem){.m-lg-3{margin:.75rem !important}.mt-lg-3{margin-top:.75rem !important}.mr-lg-3{margin-right:.75rem !important}.mb-lg-3{margin-bottom:.75rem !important}.ml-lg-3{margin-left:.75rem !important}.mx-lg-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-lg-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-lg-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 66.5rem){.m-lg-4{margin:1rem !important}.mt-lg-4{margin-top:1rem !important}.mr-lg-4{margin-right:1rem !important}.mb-lg-4{margin-bottom:1rem !important}.ml-lg-4{margin-left:1rem !important}.mx-lg-4{margin-right:1rem !important;margin-left:1rem !important}.my-lg-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-lg-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 66.5rem){.m-lg-5{margin:1.5rem !important}.mt-lg-5{margin-top:1.5rem !important}.mr-lg-5{margin-right:1.5rem !important}.mb-lg-5{margin-bottom:1.5rem !important}.ml-lg-5{margin-left:1.5rem !important}.mx-lg-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-lg-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-lg-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 66.5rem){.m-lg-6{margin:2rem !important}.mt-lg-6{margin-top:2rem !important}.mr-lg-6{margin-right:2rem !important}.mb-lg-6{margin-bottom:2rem !important}.ml-lg-6{margin-left:2rem !important}.mx-lg-6{margin-right:2rem !important;margin-left:2rem !important}.my-lg-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-lg-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 66.5rem){.m-lg-7{margin:2.5rem !important}.mt-lg-7{margin-top:2.5rem !important}.mr-lg-7{margin-right:2.5rem !important}.mb-lg-7{margin-bottom:2.5rem !important}.ml-lg-7{margin-left:2.5rem !important}.mx-lg-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-lg-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-lg-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 66.5rem){.m-lg-8{margin:3rem !important}.mt-lg-8{margin-top:3rem !important}.mr-lg-8{margin-right:3rem !important}.mb-lg-8{margin-bottom:3rem !important}.ml-lg-8{margin-left:3rem !important}.mx-lg-8{margin-right:3rem !important;margin-left:3rem !important}.my-lg-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-lg-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 66.5rem){.m-lg-9{margin:3.5rem !important}.mt-lg-9{margin-top:3.5rem !important}.mr-lg-9{margin-right:3.5rem !important}.mb-lg-9{margin-bottom:3.5rem !important}.ml-lg-9{margin-left:3.5rem !important}.mx-lg-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-lg-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-lg-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 66.5rem){.m-lg-10{margin:4rem !important}.mt-lg-10{margin-top:4rem !important}.mr-lg-10{margin-right:4rem !important}.mb-lg-10{margin-bottom:4rem !important}.ml-lg-10{margin-left:4rem !important}.mx-lg-10{margin-right:4rem !important;margin-left:4rem !important}.my-lg-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-lg-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 87.5rem){.m-xl-0{margin:0 !important}.mt-xl-0{margin-top:0 !important}.mr-xl-0{margin-right:0 !important}.mb-xl-0{margin-bottom:0 !important}.ml-xl-0{margin-left:0 !important}.mx-xl-0{margin-right:0 !important;margin-left:0 !important}.my-xl-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-xl-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 87.5rem){.m-xl-1{margin:.25rem !important}.mt-xl-1{margin-top:.25rem !important}.mr-xl-1{margin-right:.25rem !important}.mb-xl-1{margin-bottom:.25rem !important}.ml-xl-1{margin-left:.25rem !important}.mx-xl-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-xl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-xl-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 87.5rem){.m-xl-2{margin:.5rem !important}.mt-xl-2{margin-top:.5rem !important}.mr-xl-2{margin-right:.5rem !important}.mb-xl-2{margin-bottom:.5rem !important}.ml-xl-2{margin-left:.5rem !important}.mx-xl-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-xl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-xl-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 87.5rem){.m-xl-3{margin:.75rem !important}.mt-xl-3{margin-top:.75rem !important}.mr-xl-3{margin-right:.75rem !important}.mb-xl-3{margin-bottom:.75rem !important}.ml-xl-3{margin-left:.75rem !important}.mx-xl-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-xl-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-xl-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 87.5rem){.m-xl-4{margin:1rem !important}.mt-xl-4{margin-top:1rem !important}.mr-xl-4{margin-right:1rem !important}.mb-xl-4{margin-bottom:1rem !important}.ml-xl-4{margin-left:1rem !important}.mx-xl-4{margin-right:1rem !important;margin-left:1rem !important}.my-xl-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-xl-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 87.5rem){.m-xl-5{margin:1.5rem !important}.mt-xl-5{margin-top:1.5rem !important}.mr-xl-5{margin-right:1.5rem !important}.mb-xl-5{margin-bottom:1.5rem !important}.ml-xl-5{margin-left:1.5rem !important}.mx-xl-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-xl-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-xl-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 87.5rem){.m-xl-6{margin:2rem !important}.mt-xl-6{margin-top:2rem !important}.mr-xl-6{margin-right:2rem !important}.mb-xl-6{margin-bottom:2rem !important}.ml-xl-6{margin-left:2rem !important}.mx-xl-6{margin-right:2rem !important;margin-left:2rem !important}.my-xl-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-xl-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 87.5rem){.m-xl-7{margin:2.5rem !important}.mt-xl-7{margin-top:2.5rem !important}.mr-xl-7{margin-right:2.5rem !important}.mb-xl-7{margin-bottom:2.5rem !important}.ml-xl-7{margin-left:2.5rem !important}.mx-xl-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-xl-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-xl-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 87.5rem){.m-xl-8{margin:3rem !important}.mt-xl-8{margin-top:3rem !important}.mr-xl-8{margin-right:3rem !important}.mb-xl-8{margin-bottom:3rem !important}.ml-xl-8{margin-left:3rem !important}.mx-xl-8{margin-right:3rem !important;margin-left:3rem !important}.my-xl-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-xl-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 87.5rem){.m-xl-9{margin:3.5rem !important}.mt-xl-9{margin-top:3.5rem !important}.mr-xl-9{margin-right:3.5rem !important}.mb-xl-9{margin-bottom:3.5rem !important}.ml-xl-9{margin-left:3.5rem !important}.mx-xl-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-xl-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-xl-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 87.5rem){.m-xl-10{margin:4rem !important}.mt-xl-10{margin-top:4rem !important}.mr-xl-10{margin-right:4rem !important}.mb-xl-10{margin-bottom:4rem !important}.ml-xl-10{margin-left:4rem !important}.mx-xl-10{margin-right:4rem !important;margin-left:4rem !important}.my-xl-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-xl-10{margin-right:-4rem !important;margin-left:-4rem !important}}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-right:0 !important;padding-left:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-right:1rem !important;padding-left:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:2rem !important}.pt-6{padding-top:2rem !important}.pr-6{padding-right:2rem !important}.pb-6{padding-bottom:2rem !important}.pl-6{padding-left:2rem !important}.px-6{padding-right:2rem !important;padding-left:2rem !important}.py-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-7{padding:2.5rem !important}.pt-7{padding-top:2.5rem !important}.pr-7{padding-right:2.5rem !important}.pb-7{padding-bottom:2.5rem !important}.pl-7{padding-left:2.5rem !important}.px-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-8{padding:3rem !important}.pt-8{padding-top:3rem !important}.pr-8{padding-right:3rem !important}.pb-8{padding-bottom:3rem !important}.pl-8{padding-left:3rem !important}.px-8{padding-right:3rem !important;padding-left:3rem !important}.py-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-9{padding:3.5rem !important}.pt-9{padding-top:3.5rem !important}.pr-9{padding-right:3.5rem !important}.pb-9{padding-bottom:3.5rem !important}.pl-9{padding-left:3.5rem !important}.px-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-10{padding:4rem !important}.pt-10{padding-top:4rem !important}.pr-10{padding-right:4rem !important}.pb-10{padding-bottom:4rem !important}.pl-10{padding-left:4rem !important}.px-10{padding-right:4rem !important;padding-left:4rem !important}.py-10{padding-top:4rem !important;padding-bottom:4rem !important}@media (min-width: 20rem){.p-xs-0{padding:0 !important}.pt-xs-0{padding-top:0 !important}.pr-xs-0{padding-right:0 !important}.pb-xs-0{padding-bottom:0 !important}.pl-xs-0{padding-left:0 !important}.px-xs-0{padding-right:0 !important;padding-left:0 !important}.py-xs-0{padding-top:0 !important;padding-bottom:0 !important}.p-xs-1{padding:.25rem !important}.pt-xs-1{padding-top:.25rem !important}.pr-xs-1{padding-right:.25rem !important}.pb-xs-1{padding-bottom:.25rem !important}.pl-xs-1{padding-left:.25rem !important}.px-xs-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-xs-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-xs-2{padding:.5rem !important}.pt-xs-2{padding-top:.5rem !important}.pr-xs-2{padding-right:.5rem !important}.pb-xs-2{padding-bottom:.5rem !important}.pl-xs-2{padding-left:.5rem !important}.px-xs-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-xs-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-xs-3{padding:.75rem !important}.pt-xs-3{padding-top:.75rem !important}.pr-xs-3{padding-right:.75rem !important}.pb-xs-3{padding-bottom:.75rem !important}.pl-xs-3{padding-left:.75rem !important}.px-xs-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-xs-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-xs-4{padding:1rem !important}.pt-xs-4{padding-top:1rem !important}.pr-xs-4{padding-right:1rem !important}.pb-xs-4{padding-bottom:1rem !important}.pl-xs-4{padding-left:1rem !important}.px-xs-4{padding-right:1rem !important;padding-left:1rem !important}.py-xs-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-xs-5{padding:1.5rem !important}.pt-xs-5{padding-top:1.5rem !important}.pr-xs-5{padding-right:1.5rem !important}.pb-xs-5{padding-bottom:1.5rem !important}.pl-xs-5{padding-left:1.5rem !important}.px-xs-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-xs-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-xs-6{padding:2rem !important}.pt-xs-6{padding-top:2rem !important}.pr-xs-6{padding-right:2rem !important}.pb-xs-6{padding-bottom:2rem !important}.pl-xs-6{padding-left:2rem !important}.px-xs-6{padding-right:2rem !important;padding-left:2rem !important}.py-xs-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-xs-7{padding:2.5rem !important}.pt-xs-7{padding-top:2.5rem !important}.pr-xs-7{padding-right:2.5rem !important}.pb-xs-7{padding-bottom:2.5rem !important}.pl-xs-7{padding-left:2.5rem !important}.px-xs-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-xs-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-xs-8{padding:3rem !important}.pt-xs-8{padding-top:3rem !important}.pr-xs-8{padding-right:3rem !important}.pb-xs-8{padding-bottom:3rem !important}.pl-xs-8{padding-left:3rem !important}.px-xs-8{padding-right:3rem !important;padding-left:3rem !important}.py-xs-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-xs-9{padding:3.5rem !important}.pt-xs-9{padding-top:3.5rem !important}.pr-xs-9{padding-right:3.5rem !important}.pb-xs-9{padding-bottom:3.5rem !important}.pl-xs-9{padding-left:3.5rem !important}.px-xs-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-xs-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-xs-10{padding:4rem !important}.pt-xs-10{padding-top:4rem !important}.pr-xs-10{padding-right:4rem !important}.pb-xs-10{padding-bottom:4rem !important}.pl-xs-10{padding-left:4rem !important}.px-xs-10{padding-right:4rem !important;padding-left:4rem !important}.py-xs-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 31.25rem){.p-sm-0{padding:0 !important}.pt-sm-0{padding-top:0 !important}.pr-sm-0{padding-right:0 !important}.pb-sm-0{padding-bottom:0 !important}.pl-sm-0{padding-left:0 !important}.px-sm-0{padding-right:0 !important;padding-left:0 !important}.py-sm-0{padding-top:0 !important;padding-bottom:0 !important}.p-sm-1{padding:.25rem !important}.pt-sm-1{padding-top:.25rem !important}.pr-sm-1{padding-right:.25rem !important}.pb-sm-1{padding-bottom:.25rem !important}.pl-sm-1{padding-left:.25rem !important}.px-sm-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-sm-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-sm-2{padding:.5rem !important}.pt-sm-2{padding-top:.5rem !important}.pr-sm-2{padding-right:.5rem !important}.pb-sm-2{padding-bottom:.5rem !important}.pl-sm-2{padding-left:.5rem !important}.px-sm-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-sm-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-sm-3{padding:.75rem !important}.pt-sm-3{padding-top:.75rem !important}.pr-sm-3{padding-right:.75rem !important}.pb-sm-3{padding-bottom:.75rem !important}.pl-sm-3{padding-left:.75rem !important}.px-sm-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-sm-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-sm-4{padding:1rem !important}.pt-sm-4{padding-top:1rem !important}.pr-sm-4{padding-right:1rem !important}.pb-sm-4{padding-bottom:1rem !important}.pl-sm-4{padding-left:1rem !important}.px-sm-4{padding-right:1rem !important;padding-left:1rem !important}.py-sm-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-sm-5{padding:1.5rem !important}.pt-sm-5{padding-top:1.5rem !important}.pr-sm-5{padding-right:1.5rem !important}.pb-sm-5{padding-bottom:1.5rem !important}.pl-sm-5{padding-left:1.5rem !important}.px-sm-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-sm-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-sm-6{padding:2rem !important}.pt-sm-6{padding-top:2rem !important}.pr-sm-6{padding-right:2rem !important}.pb-sm-6{padding-bottom:2rem !important}.pl-sm-6{padding-left:2rem !important}.px-sm-6{padding-right:2rem !important;padding-left:2rem !important}.py-sm-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-sm-7{padding:2.5rem !important}.pt-sm-7{padding-top:2.5rem !important}.pr-sm-7{padding-right:2.5rem !important}.pb-sm-7{padding-bottom:2.5rem !important}.pl-sm-7{padding-left:2.5rem !important}.px-sm-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-sm-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-sm-8{padding:3rem !important}.pt-sm-8{padding-top:3rem !important}.pr-sm-8{padding-right:3rem !important}.pb-sm-8{padding-bottom:3rem !important}.pl-sm-8{padding-left:3rem !important}.px-sm-8{padding-right:3rem !important;padding-left:3rem !important}.py-sm-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-sm-9{padding:3.5rem !important}.pt-sm-9{padding-top:3.5rem !important}.pr-sm-9{padding-right:3.5rem !important}.pb-sm-9{padding-bottom:3.5rem !important}.pl-sm-9{padding-left:3.5rem !important}.px-sm-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-sm-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-sm-10{padding:4rem !important}.pt-sm-10{padding-top:4rem !important}.pr-sm-10{padding-right:4rem !important}.pb-sm-10{padding-bottom:4rem !important}.pl-sm-10{padding-left:4rem !important}.px-sm-10{padding-right:4rem !important;padding-left:4rem !important}.py-sm-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 50rem){.p-md-0{padding:0 !important}.pt-md-0{padding-top:0 !important}.pr-md-0{padding-right:0 !important}.pb-md-0{padding-bottom:0 !important}.pl-md-0{padding-left:0 !important}.px-md-0{padding-right:0 !important;padding-left:0 !important}.py-md-0{padding-top:0 !important;padding-bottom:0 !important}.p-md-1{padding:.25rem !important}.pt-md-1{padding-top:.25rem !important}.pr-md-1{padding-right:.25rem !important}.pb-md-1{padding-bottom:.25rem !important}.pl-md-1{padding-left:.25rem !important}.px-md-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-md-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-md-2{padding:.5rem !important}.pt-md-2{padding-top:.5rem !important}.pr-md-2{padding-right:.5rem !important}.pb-md-2{padding-bottom:.5rem !important}.pl-md-2{padding-left:.5rem !important}.px-md-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-md-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-md-3{padding:.75rem !important}.pt-md-3{padding-top:.75rem !important}.pr-md-3{padding-right:.75rem !important}.pb-md-3{padding-bottom:.75rem !important}.pl-md-3{padding-left:.75rem !important}.px-md-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-md-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-md-4{padding:1rem !important}.pt-md-4{padding-top:1rem !important}.pr-md-4{padding-right:1rem !important}.pb-md-4{padding-bottom:1rem !important}.pl-md-4{padding-left:1rem !important}.px-md-4{padding-right:1rem !important;padding-left:1rem !important}.py-md-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-md-5{padding:1.5rem !important}.pt-md-5{padding-top:1.5rem !important}.pr-md-5{padding-right:1.5rem !important}.pb-md-5{padding-bottom:1.5rem !important}.pl-md-5{padding-left:1.5rem !important}.px-md-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-md-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-md-6{padding:2rem !important}.pt-md-6{padding-top:2rem !important}.pr-md-6{padding-right:2rem !important}.pb-md-6{padding-bottom:2rem !important}.pl-md-6{padding-left:2rem !important}.px-md-6{padding-right:2rem !important;padding-left:2rem !important}.py-md-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-md-7{padding:2.5rem !important}.pt-md-7{padding-top:2.5rem !important}.pr-md-7{padding-right:2.5rem !important}.pb-md-7{padding-bottom:2.5rem !important}.pl-md-7{padding-left:2.5rem !important}.px-md-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-md-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-md-8{padding:3rem !important}.pt-md-8{padding-top:3rem !important}.pr-md-8{padding-right:3rem !important}.pb-md-8{padding-bottom:3rem !important}.pl-md-8{padding-left:3rem !important}.px-md-8{padding-right:3rem !important;padding-left:3rem !important}.py-md-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-md-9{padding:3.5rem !important}.pt-md-9{padding-top:3.5rem !important}.pr-md-9{padding-right:3.5rem !important}.pb-md-9{padding-bottom:3.5rem !important}.pl-md-9{padding-left:3.5rem !important}.px-md-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-md-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-md-10{padding:4rem !important}.pt-md-10{padding-top:4rem !important}.pr-md-10{padding-right:4rem !important}.pb-md-10{padding-bottom:4rem !important}.pl-md-10{padding-left:4rem !important}.px-md-10{padding-right:4rem !important;padding-left:4rem !important}.py-md-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 66.5rem){.p-lg-0{padding:0 !important}.pt-lg-0{padding-top:0 !important}.pr-lg-0{padding-right:0 !important}.pb-lg-0{padding-bottom:0 !important}.pl-lg-0{padding-left:0 !important}.px-lg-0{padding-right:0 !important;padding-left:0 !important}.py-lg-0{padding-top:0 !important;padding-bottom:0 !important}.p-lg-1{padding:.25rem !important}.pt-lg-1{padding-top:.25rem !important}.pr-lg-1{padding-right:.25rem !important}.pb-lg-1{padding-bottom:.25rem !important}.pl-lg-1{padding-left:.25rem !important}.px-lg-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-lg-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-lg-2{padding:.5rem !important}.pt-lg-2{padding-top:.5rem !important}.pr-lg-2{padding-right:.5rem !important}.pb-lg-2{padding-bottom:.5rem !important}.pl-lg-2{padding-left:.5rem !important}.px-lg-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-lg-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-lg-3{padding:.75rem !important}.pt-lg-3{padding-top:.75rem !important}.pr-lg-3{padding-right:.75rem !important}.pb-lg-3{padding-bottom:.75rem !important}.pl-lg-3{padding-left:.75rem !important}.px-lg-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-lg-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-lg-4{padding:1rem !important}.pt-lg-4{padding-top:1rem !important}.pr-lg-4{padding-right:1rem !important}.pb-lg-4{padding-bottom:1rem !important}.pl-lg-4{padding-left:1rem !important}.px-lg-4{padding-right:1rem !important;padding-left:1rem !important}.py-lg-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-lg-5{padding:1.5rem !important}.pt-lg-5{padding-top:1.5rem !important}.pr-lg-5{padding-right:1.5rem !important}.pb-lg-5{padding-bottom:1.5rem !important}.pl-lg-5{padding-left:1.5rem !important}.px-lg-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-lg-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-lg-6{padding:2rem !important}.pt-lg-6{padding-top:2rem !important}.pr-lg-6{padding-right:2rem !important}.pb-lg-6{padding-bottom:2rem !important}.pl-lg-6{padding-left:2rem !important}.px-lg-6{padding-right:2rem !important;padding-left:2rem !important}.py-lg-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-lg-7{padding:2.5rem !important}.pt-lg-7{padding-top:2.5rem !important}.pr-lg-7{padding-right:2.5rem !important}.pb-lg-7{padding-bottom:2.5rem !important}.pl-lg-7{padding-left:2.5rem !important}.px-lg-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-lg-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-lg-8{padding:3rem !important}.pt-lg-8{padding-top:3rem !important}.pr-lg-8{padding-right:3rem !important}.pb-lg-8{padding-bottom:3rem !important}.pl-lg-8{padding-left:3rem !important}.px-lg-8{padding-right:3rem !important;padding-left:3rem !important}.py-lg-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-lg-9{padding:3.5rem !important}.pt-lg-9{padding-top:3.5rem !important}.pr-lg-9{padding-right:3.5rem !important}.pb-lg-9{padding-bottom:3.5rem !important}.pl-lg-9{padding-left:3.5rem !important}.px-lg-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-lg-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-lg-10{padding:4rem !important}.pt-lg-10{padding-top:4rem !important}.pr-lg-10{padding-right:4rem !important}.pb-lg-10{padding-bottom:4rem !important}.pl-lg-10{padding-left:4rem !important}.px-lg-10{padding-right:4rem !important;padding-left:4rem !important}.py-lg-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 87.5rem){.p-xl-0{padding:0 !important}.pt-xl-0{padding-top:0 !important}.pr-xl-0{padding-right:0 !important}.pb-xl-0{padding-bottom:0 !important}.pl-xl-0{padding-left:0 !important}.px-xl-0{padding-right:0 !important;padding-left:0 !important}.py-xl-0{padding-top:0 !important;padding-bottom:0 !important}.p-xl-1{padding:.25rem !important}.pt-xl-1{padding-top:.25rem !important}.pr-xl-1{padding-right:.25rem !important}.pb-xl-1{padding-bottom:.25rem !important}.pl-xl-1{padding-left:.25rem !important}.px-xl-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-xl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-xl-2{padding:.5rem !important}.pt-xl-2{padding-top:.5rem !important}.pr-xl-2{padding-right:.5rem !important}.pb-xl-2{padding-bottom:.5rem !important}.pl-xl-2{padding-left:.5rem !important}.px-xl-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-xl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-xl-3{padding:.75rem !important}.pt-xl-3{padding-top:.75rem !important}.pr-xl-3{padding-right:.75rem !important}.pb-xl-3{padding-bottom:.75rem !important}.pl-xl-3{padding-left:.75rem !important}.px-xl-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-xl-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-xl-4{padding:1rem !important}.pt-xl-4{padding-top:1rem !important}.pr-xl-4{padding-right:1rem !important}.pb-xl-4{padding-bottom:1rem !important}.pl-xl-4{padding-left:1rem !important}.px-xl-4{padding-right:1rem !important;padding-left:1rem !important}.py-xl-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-xl-5{padding:1.5rem !important}.pt-xl-5{padding-top:1.5rem !important}.pr-xl-5{padding-right:1.5rem !important}.pb-xl-5{padding-bottom:1.5rem !important}.pl-xl-5{padding-left:1.5rem !important}.px-xl-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-xl-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-xl-6{padding:2rem !important}.pt-xl-6{padding-top:2rem !important}.pr-xl-6{padding-right:2rem !important}.pb-xl-6{padding-bottom:2rem !important}.pl-xl-6{padding-left:2rem !important}.px-xl-6{padding-right:2rem !important;padding-left:2rem !important}.py-xl-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-xl-7{padding:2.5rem !important}.pt-xl-7{padding-top:2.5rem !important}.pr-xl-7{padding-right:2.5rem !important}.pb-xl-7{padding-bottom:2.5rem !important}.pl-xl-7{padding-left:2.5rem !important}.px-xl-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-xl-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-xl-8{padding:3rem !important}.pt-xl-8{padding-top:3rem !important}.pr-xl-8{padding-right:3rem !important}.pb-xl-8{padding-bottom:3rem !important}.pl-xl-8{padding-left:3rem !important}.px-xl-8{padding-right:3rem !important;padding-left:3rem !important}.py-xl-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-xl-9{padding:3.5rem !important}.pt-xl-9{padding-top:3.5rem !important}.pr-xl-9{padding-right:3.5rem !important}.pb-xl-9{padding-bottom:3.5rem !important}.pl-xl-9{padding-left:3.5rem !important}.px-xl-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-xl-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-xl-10{padding:4rem !important}.pt-xl-10{padding-top:4rem !important}.pr-xl-10{padding-right:4rem !important}.pb-xl-10{padding-bottom:4rem !important}.pl-xl-10{padding-left:4rem !important}.px-xl-10{padding-right:4rem !important;padding-left:4rem !important}.py-xl-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media print{.site-footer,.site-button,#edit-this-page,#back-to-top,.site-nav,.main-header{display:none !important}.side-bar{width:100%;height:auto;border-right:0 !important}.site-header{border-bottom:1px solid #eeebee}.site-title{font-size:16px !important;font-weight:700 !important}.text-small{font-size:8pt !important}pre.highlight{border:1px solid #eeebee}.main{max-width:none;margin-left:0}}a.skip-to-main{left:-999px;position:absolute;top:auto;width:1px;height:1px;overflow:hidden;z-index:-999}a.skip-to-main:focus,a.skip-to-main:active{color:#53a3da;background-color:#fff;left:auto;top:auto;width:30%;height:auto;overflow:auto;margin:10px 35%;padding:5px;border-radius:15px;border:4px solid #5e41d0;text-align:center;font-size:1.2em;z-index:999}div.opaque{background-color:#fff} diff --git a/assets/css/just-the-docs-light.css b/assets/css/just-the-docs-light.css new file mode 100644 index 0000000000..1384731931 --- /dev/null +++ b/assets/css/just-the-docs-light.css @@ -0,0 +1 @@ +.highlight .c{color:#586e75}.highlight .err{color:#93a1a1}.highlight .g{color:#93a1a1}.highlight .k{color:#859900}.highlight .l{color:#93a1a1}.highlight .n{color:#93a1a1}.highlight .o{color:#859900}.highlight .x{color:#cb4b16}.highlight .p{color:#93a1a1}.highlight .cm{color:#586e75}.highlight .cp{color:#859900}.highlight .c1{color:#586e75}.highlight .cs{color:#859900}.highlight .gd{color:#2aa198}.highlight .ge{font-style:italic;color:#93a1a1}.highlight .gr{color:#dc322f}.highlight .gh{color:#cb4b16}.highlight .gi{color:#859900}.highlight .go{color:#93a1a1}.highlight .gp{color:#93a1a1}.highlight .gs{font-weight:bold;color:#93a1a1}.highlight .gu{color:#cb4b16}.highlight .gt{color:#93a1a1}.highlight .kc{color:#cb4b16}.highlight .kd{color:#268bd2}.highlight .kn{color:#859900}.highlight .kp{color:#859900}.highlight .kr{color:#268bd2}.highlight .kt{color:#dc322f}.highlight .ld{color:#93a1a1}.highlight .m{color:#2aa198}.highlight .s{color:#2aa198}.highlight .na{color:#555}.highlight .nb{color:#b58900}.highlight .nc{color:#268bd2}.highlight .no{color:#cb4b16}.highlight .nd{color:#268bd2}.highlight .ni{color:#cb4b16}.highlight .ne{color:#cb4b16}.highlight .nf{color:#268bd2}.highlight .nl{color:#555}.highlight .nn{color:#93a1a1}.highlight .nx{color:#555}.highlight .py{color:#93a1a1}.highlight .nt{color:#268bd2}.highlight .nv{color:#268bd2}.highlight .ow{color:#859900}.highlight .w{color:#93a1a1}.highlight .mf{color:#2aa198}.highlight .mh{color:#2aa198}.highlight .mi{color:#2aa198}.highlight .mo{color:#2aa198}.highlight .sb{color:#586e75}.highlight .sc{color:#2aa198}.highlight .sd{color:#93a1a1}.highlight .s2{color:#2aa198}.highlight .se{color:#cb4b16}.highlight .sh{color:#93a1a1}.highlight .si{color:#2aa198}.highlight .sx{color:#2aa198}.highlight .sr{color:#dc322f}.highlight .s1{color:#2aa198}.highlight .ss{color:#2aa198}.highlight .bp{color:#268bd2}.highlight .vc{color:#268bd2}.highlight .vg{color:#268bd2}.highlight .vi{color:#268bd2}.highlight .il{color:#2aa198}.highlight .c{color:#586e75}.highlight .err{color:#93a1a1}.highlight .g{color:#93a1a1}.highlight .k{color:#859900}.highlight .l{color:#93a1a1}.highlight .n{color:#93a1a1}.highlight .o{color:#859900}.highlight .x{color:#cb4b16}.highlight .p{color:#93a1a1}.highlight .cm{color:#586e75}.highlight .cp{color:#859900}.highlight .c1{color:#586e75}.highlight .cs{color:#859900}.highlight .gd{color:#2aa198}.highlight .ge{font-style:italic;color:#93a1a1}.highlight .gr{color:#dc322f}.highlight .gh{color:#cb4b16}.highlight .gi{color:#859900}.highlight .go{color:#93a1a1}.highlight .gp{color:#93a1a1}.highlight .gs{font-weight:bold;color:#93a1a1}.highlight .gu{color:#cb4b16}.highlight .gt{color:#93a1a1}.highlight .kc{color:#cb4b16}.highlight .kd{color:#268bd2}.highlight .kn{color:#859900}.highlight .kp{color:#859900}.highlight .kr{color:#268bd2}.highlight .kt{color:#dc322f}.highlight .ld{color:#93a1a1}.highlight .m{color:#2aa198}.highlight .s{color:#2aa198}.highlight .na{color:#555}.highlight .nb{color:#b58900}.highlight .nc{color:#268bd2}.highlight .no{color:#cb4b16}.highlight .nd{color:#268bd2}.highlight .ni{color:#cb4b16}.highlight .ne{color:#cb4b16}.highlight .nf{color:#268bd2}.highlight .nl{color:#555}.highlight .nn{color:#93a1a1}.highlight .nx{color:#555}.highlight .py{color:#93a1a1}.highlight .nt{color:#268bd2}.highlight .nv{color:#268bd2}.highlight .ow{color:#859900}.highlight .w{color:#93a1a1}.highlight .mf{color:#2aa198}.highlight .mh{color:#2aa198}.highlight .mi{color:#2aa198}.highlight .mo{color:#2aa198}.highlight .sb{color:#586e75}.highlight .sc{color:#2aa198}.highlight .sd{color:#93a1a1}.highlight .s2{color:#2aa198}.highlight .se{color:#cb4b16}.highlight .sh{color:#93a1a1}.highlight .si{color:#2aa198}.highlight .sx{color:#2aa198}.highlight .sr{color:#dc322f}.highlight .s1{color:#2aa198}.highlight .ss{color:#2aa198}.highlight .bp{color:#268bd2}.highlight .vc{color:#268bd2}.highlight .vg{color:#268bd2}.highlight .vi{color:#268bd2}.highlight .il{color:#2aa198}/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}main{display:block}h1{font-size:2em;margin:0.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace, monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace, monospace;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}button,[type="button"],[type="reset"],[type="submit"]{-webkit-appearance:button}button::-moz-focus-inner,[type="button"]::-moz-focus-inner,[type="reset"]::-moz-focus-inner,[type="submit"]::-moz-focus-inner{border-style:none;padding:0}button:-moz-focusring,[type="button"]:-moz-focusring,[type="reset"]:-moz-focusring,[type="submit"]:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:0.35em 0.75em 0.625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type="checkbox"],[type="radio"]{box-sizing:border-box;padding:0}[type="number"]::-webkit-inner-spin-button,[type="number"]::-webkit-outer-spin-button{height:auto}[type="search"]{-webkit-appearance:textfield;outline-offset:-2px}[type="search"]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}template{display:none}[hidden]{display:none}*{box-sizing:border-box}::selection{color:#fff;background:#7253ed}html{font-size:14px !important;scroll-behavior:smooth}@media (min-width: 31.25rem){html{font-size:16px !important}}body{font-family:system-ui,-apple-system,blinkmacsystemfont,"Segoe UI",roboto,"Helvetica Neue",arial,sans-serif;font-size:inherit;line-height:1.4;color:#5c5962;background-color:#fff;overflow-wrap:break-word}ol,ul,dl,pre,address,blockquote,table,div,hr,form,fieldset,noscript .table-wrapper{margin-top:0}h1,h2,h3,h4,h5,h6,#toctitle{margin-top:0;margin-bottom:1em;font-weight:500;line-height:1.25;color:#27262b}p{margin-top:1em;margin-bottom:1em}a{color:#7253ed;text-decoration:none}a:not([class]){text-decoration:underline;text-decoration-color:#eeebee;text-underline-offset:2px}a:not([class]):hover{text-decoration-color:rgba(114,83,237,0.45)}code{font-family:"SFMono-Regular",menlo,consolas,monospace;font-size:0.75em;line-height:1.4}figure,pre{margin:0}li{margin:0.25em 0}img{max-width:100%;height:auto}hr{height:1px;padding:0;margin:2rem 0;background-color:#eeebee;border:0}blockquote{margin:10px 0;margin-block-start:0;margin-inline-start:0;padding-left:15px;border-left:3px solid #eeebee}.side-bar{z-index:0;display:flex;flex-wrap:wrap;background-color:#f5f6fa}@media (min-width: 50rem){.side-bar{flex-flow:column nowrap;position:fixed;width:248px;height:100%;border-right:1px solid #eeebee;align-items:flex-end}}@media (min-width: 66.5rem){.side-bar{width:calc((100% - 1064px) / 2 + 264px);min-width:264px}}@media (min-width: 50rem){.main{position:relative;max-width:800px;margin-left:248px}}@media (min-width: 66.5rem){.main{margin-left:Max(264px, calc((100% - 1064px) / 2 + 264px))}}.main-content-wrap{padding-right:1rem;padding-left:1rem;padding-top:1rem;padding-bottom:1rem}@media (min-width: 50rem){.main-content-wrap{padding-right:2rem;padding-left:2rem}}@media (min-width: 50rem){.main-content-wrap{padding-top:2rem;padding-bottom:2rem}}.main-header{z-index:0;display:none;background-color:#f5f6fa}@media (min-width: 50rem){.main-header{display:flex;justify-content:space-between;height:60px;background-color:#fff;border-bottom:1px solid #eeebee}}.main-header.nav-open{display:block}@media (min-width: 50rem){.main-header.nav-open{display:flex}}.site-nav,.site-header,.site-footer{width:100%}@media (min-width: 66.5rem){.site-nav,.site-header,.site-footer{width:264px}}.site-nav{display:none}.site-nav.nav-open{display:block}@media (min-width: 50rem){.site-nav{display:block;padding-top:3rem;padding-bottom:1rem;overflow-y:auto;flex:1 1 auto}}.site-header{display:flex;min-height:60px;align-items:center}@media (min-width: 50rem){.site-header{height:60px;max-height:60px;border-bottom:1px solid #eeebee}}.site-title{padding-right:1rem;padding-left:1rem;flex-grow:1;display:flex;height:100%;align-items:center;padding-top:.75rem;padding-bottom:.75rem;color:#27262b;font-size:18px !important}@media (min-width: 50rem){.site-title{padding-right:2rem;padding-left:2rem}}@media (min-width: 31.25rem){.site-title{font-size:24px !important;line-height:1.25}}@media (min-width: 50rem){.site-title{padding-top:.5rem;padding-bottom:.5rem}}.site-button{display:flex;height:100%;padding:1rem;align-items:center}@media (min-width: 50rem){.site-header .site-button{display:none}}.site-title:hover{background-image:linear-gradient(-90deg, #ebedf5 0%, rgba(235,237,245,0.8) 80%, rgba(235,237,245,0) 100%)}.site-button:hover{background-image:linear-gradient(-90deg, #ebedf5 0%, rgba(235,237,245,0.8) 100%)}body{position:relative;padding-bottom:4rem;overflow-y:scroll}@media (min-width: 50rem){body{position:static;padding-bottom:0}}.site-footer{padding-right:1rem;padding-left:1rem;position:absolute;bottom:0;left:0;padding-top:1rem;padding-bottom:1rem;color:#959396;font-size:11px !important}@media (min-width: 50rem){.site-footer{padding-right:2rem;padding-left:2rem}}@media (min-width: 31.25rem){.site-footer{font-size:12px !important}}@media (min-width: 50rem){.site-footer{position:static;justify-self:end}}.icon{width:1.5rem;height:1.5rem;color:#7253ed}.main-content{line-height:1.6}.main-content ol,.main-content ul,.main-content dl,.main-content pre,.main-content address,.main-content blockquote,.main-content .table-wrapper{margin-top:0.5em}.main-content a{overflow:hidden;text-overflow:ellipsis}.main-content ul,.main-content ol{padding-left:1.5em}.main-content li .highlight{margin-top:.25rem}.main-content ol{list-style-type:none;counter-reset:step-counter}.main-content ol>li{position:relative}.main-content ol>li::before{position:absolute;top:0.2em;left:-1.6em;color:#959396;content:counter(step-counter);counter-increment:step-counter;font-size:12px !important}@media (min-width: 31.25rem){.main-content ol>li::before{font-size:14px !important}}@media (min-width: 31.25rem){.main-content ol>li::before{top:0.11em}}.main-content ol>li ol{counter-reset:sub-counter}.main-content ol>li ol>li::before{content:counter(sub-counter,lower-alpha);counter-increment:sub-counter}.main-content ul{list-style:none}.main-content ul>li::before{position:absolute;margin-left:-1.4em;color:#959396;content:"•"}.main-content .task-list-item::before{content:""}.main-content .task-list-item-checkbox{margin-right:0.6em;margin-left:-1.4em}.main-content hr+*{margin-top:0}.main-content h1:first-of-type{margin-top:0.5em}.main-content dl{display:grid;grid-template:auto / 10em 1fr}.main-content dt,.main-content dd{margin:0.25em 0}.main-content dt{grid-column:1;font-weight:500;text-align:right}.main-content dt::after{content:":"}.main-content dd{grid-column:2;margin-bottom:0;margin-left:1em}.main-content dd blockquote:first-child,.main-content dd div:first-child,.main-content dd dl:first-child,.main-content dd dt:first-child,.main-content dd h1:first-child,.main-content dd h2:first-child,.main-content dd h3:first-child,.main-content dd h4:first-child,.main-content dd h5:first-child,.main-content dd h6:first-child,.main-content dd li:first-child,.main-content dd ol:first-child,.main-content dd p:first-child,.main-content dd pre:first-child,.main-content dd table:first-child,.main-content dd ul:first-child,.main-content dd .table-wrapper:first-child{margin-top:0}.main-content dd dl:first-child dt:first-child,.main-content dd dl:first-child dd:nth-child(2),.main-content ol dl:first-child dt:first-child,.main-content ol dl:first-child dd:nth-child(2),.main-content ul dl:first-child dt:first-child,.main-content ul dl:first-child dd:nth-child(2){margin-top:0}.main-content .anchor-heading{position:absolute;right:-1rem;width:1.5rem;height:100%;padding-right:.25rem;padding-left:.25rem;overflow:visible}@media (min-width: 50rem){.main-content .anchor-heading{right:auto;left:-1.5rem}}.main-content .anchor-heading svg{display:inline-block;width:100%;height:100%;color:#7253ed;visibility:hidden}.main-content .anchor-heading:hover svg,.main-content .anchor-heading:focus svg,.main-content h1:hover>.anchor-heading svg,.main-content h2:hover>.anchor-heading svg,.main-content h3:hover>.anchor-heading svg,.main-content h4:hover>.anchor-heading svg,.main-content h5:hover>.anchor-heading svg,.main-content h6:hover>.anchor-heading svg{visibility:visible}.main-content summary{cursor:pointer}.main-content h1,.main-content h2,.main-content h3,.main-content h4,.main-content h5,.main-content h6,.main-content #toctitle{position:relative;margin-top:1.5em;margin-bottom:0.25em}.main-content h1+table,.main-content h1+.table-wrapper,.main-content h1+.code-example,.main-content h1+.highlighter-rouge,.main-content h1+.sectionbody .listingblock,.main-content h2+table,.main-content h2+.table-wrapper,.main-content h2+.code-example,.main-content h2+.highlighter-rouge,.main-content h2+.sectionbody .listingblock,.main-content h3+table,.main-content h3+.table-wrapper,.main-content h3+.code-example,.main-content h3+.highlighter-rouge,.main-content h3+.sectionbody .listingblock,.main-content h4+table,.main-content h4+.table-wrapper,.main-content h4+.code-example,.main-content h4+.highlighter-rouge,.main-content h4+.sectionbody .listingblock,.main-content h5+table,.main-content h5+.table-wrapper,.main-content h5+.code-example,.main-content h5+.highlighter-rouge,.main-content h5+.sectionbody .listingblock,.main-content h6+table,.main-content h6+.table-wrapper,.main-content h6+.code-example,.main-content h6+.highlighter-rouge,.main-content h6+.sectionbody .listingblock,.main-content #toctitle+table,.main-content #toctitle+.table-wrapper,.main-content #toctitle+.code-example,.main-content #toctitle+.highlighter-rouge,.main-content #toctitle+.sectionbody .listingblock{margin-top:1em}.main-content h1+p:not(.label),.main-content h2+p:not(.label),.main-content h3+p:not(.label),.main-content h4+p:not(.label),.main-content h5+p:not(.label),.main-content h6+p:not(.label),.main-content #toctitle+p:not(.label){margin-top:0}.main-content>h1:first-child,.main-content>h2:first-child,.main-content>h3:first-child,.main-content>h4:first-child,.main-content>h5:first-child,.main-content>h6:first-child,.main-content>.sect1:first-child>h2,.main-content>.sect2:first-child>h3,.main-content>.sect3:first-child>h4,.main-content>.sect4:first-child>h5,.main-content>.sect5:first-child>h6{margin-top:.5rem}.nav-list{padding:0;margin-top:0;margin-bottom:0;list-style:none}.nav-list .nav-list-item{font-size:14px !important;position:relative;margin:0}@media (min-width: 31.25rem){.nav-list .nav-list-item{font-size:16px !important}}@media (min-width: 50rem){.nav-list .nav-list-item{font-size:12px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.nav-list .nav-list-item{font-size:14px !important}}.nav-list .nav-list-item .nav-list-link{display:block;min-height:3rem;padding-top:.25rem;padding-bottom:.25rem;line-height:2.5rem;padding-right:3rem;padding-left:1rem}@media (min-width: 50rem){.nav-list .nav-list-item .nav-list-link{min-height:2rem;line-height:1.5rem;padding-right:2rem;padding-left:2rem}}.nav-list .nav-list-item .nav-list-link.external>svg{width:1rem;height:1rem;vertical-align:text-bottom}.nav-list .nav-list-item .nav-list-link.active{font-weight:600;text-decoration:none}.nav-list .nav-list-item .nav-list-link:hover,.nav-list .nav-list-item .nav-list-link.active{background-image:linear-gradient(-90deg, #ebedf5 0%, rgba(235,237,245,0.8) 80%, rgba(235,237,245,0) 100%)}.nav-list .nav-list-item .nav-list-expander{position:absolute;right:0;width:3rem;height:3rem;padding:.75rem;color:#7253ed}@media (min-width: 50rem){.nav-list .nav-list-item .nav-list-expander{width:2rem;height:2rem;padding:.5rem}}.nav-list .nav-list-item .nav-list-expander:hover{background-image:linear-gradient(-90deg, #ebedf5 0%, rgba(235,237,245,0.8) 100%)}.nav-list .nav-list-item .nav-list-expander svg{transform:rotate(90deg)}.nav-list .nav-list-item>.nav-list{display:none;padding-left:.75rem;list-style:none}.nav-list .nav-list-item>.nav-list .nav-list-item{position:relative}.nav-list .nav-list-item>.nav-list .nav-list-item .nav-list-link{color:#5c5962}.nav-list .nav-list-item>.nav-list .nav-list-item .nav-list-expander{color:#5c5962}.nav-list .nav-list-item.active>.nav-list-expander svg{transform:rotate(-90deg)}.nav-list .nav-list-item.active>.nav-list{display:block}.nav-category{padding:.5rem 1rem;font-weight:600;text-align:start;text-transform:uppercase;border-bottom:1px solid #eeebee;font-size:11px !important}@media (min-width: 31.25rem){.nav-category{font-size:12px !important}}@media (min-width: 50rem){.nav-category{padding:.5rem 2rem;margin-top:1rem;text-align:start}.nav-category:first-child{margin-top:0}}.nav-list.nav-category-list>.nav-list-item{margin:0}.nav-list.nav-category-list>.nav-list-item>.nav-list{padding:0}.nav-list.nav-category-list>.nav-list-item>.nav-list>.nav-list-item>.nav-list-link{color:#7253ed}.nav-list.nav-category-list>.nav-list-item>.nav-list>.nav-list-item>.nav-list-expander{color:#7253ed}.aux-nav{height:100%;overflow-x:auto;font-size:11px !important}@media (min-width: 31.25rem){.aux-nav{font-size:12px !important}}.aux-nav .aux-nav-list{display:flex;height:100%;padding:0;margin:0;list-style:none}.aux-nav .aux-nav-list-item{display:inline-block;height:100%;padding:0;margin:0}@media (min-width: 50rem){.aux-nav{padding-right:1rem}}@media (min-width: 50rem){.breadcrumb-nav{margin-top:-1rem}}.breadcrumb-nav-list{padding-left:0;margin-bottom:.75rem;list-style:none}.breadcrumb-nav-list-item{display:table-cell;font-size:11px !important}@media (min-width: 31.25rem){.breadcrumb-nav-list-item{font-size:12px !important}}.breadcrumb-nav-list-item::before{display:none}.breadcrumb-nav-list-item::after{display:inline-block;margin-right:.5rem;margin-left:.5rem;color:#959396;content:"/"}.breadcrumb-nav-list-item:last-child::after{content:""}h1,.text-alpha{font-size:32px !important;line-height:1.25;font-weight:300}@media (min-width: 31.25rem){h1,.text-alpha{font-size:36px !important}}h2,.text-beta,#toctitle{font-size:18px !important}@media (min-width: 31.25rem){h2,.text-beta,#toctitle{font-size:24px !important;line-height:1.25}}h3,.text-gamma{font-size:16px !important}@media (min-width: 31.25rem){h3,.text-gamma{font-size:18px !important}}h4,.text-delta{font-size:11px !important;font-weight:400;text-transform:uppercase;letter-spacing:0.1em}@media (min-width: 31.25rem){h4,.text-delta{font-size:12px !important}}h4 code{text-transform:none}h5,.text-epsilon{font-size:12px !important}@media (min-width: 31.25rem){h5,.text-epsilon{font-size:14px !important}}h6,.text-zeta{font-size:11px !important}@media (min-width: 31.25rem){h6,.text-zeta{font-size:12px !important}}.text-small{font-size:11px !important}@media (min-width: 31.25rem){.text-small{font-size:12px !important}}.text-mono{font-family:"SFMono-Regular",menlo,consolas,monospace !important}.text-left{text-align:left !important}.text-center{text-align:center !important}.text-right{text-align:right !important}.label,.label-blue{display:inline-block;padding:0.16em 0.56em;margin-right:.5rem;margin-left:.5rem;color:#fff;text-transform:uppercase;vertical-align:middle;background-color:#2869e6;font-size:11px !important;border-radius:12px}@media (min-width: 31.25rem){.label,.label-blue{font-size:12px !important}}.label-green{background-color:#009c7b}.label-purple{background-color:#5e41d0}.label-red{background-color:#e94c4c}.label-yellow{color:#44434d;background-color:#f7d12e}.btn{display:inline-block;box-sizing:border-box;padding:0.3em 1em;margin:0;font-family:inherit;font-size:inherit;font-weight:500;line-height:1.5;color:#7253ed;text-decoration:none;vertical-align:baseline;cursor:pointer;background-color:#f7f7f7;border-width:0;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);appearance:none}.btn:focus{text-decoration:none;outline:none;box-shadow:0 0 0 3px rgba(0,0,255,0.25)}.btn:focus:hover,.btn.selected:focus{box-shadow:0 0 0 3px rgba(0,0,255,0.25)}.btn:hover,.btn.zeroclipboard-is-hover{color:#6a4aec}.btn:hover,.btn:active,.btn.zeroclipboard-is-hover,.btn.zeroclipboard-is-active{text-decoration:none;background-color:#f4f4f4}.btn:active,.btn.selected,.btn.zeroclipboard-is-active{background-color:#efefef;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn.selected:hover{background-color:#cfcfcf}.btn:disabled,.btn:disabled:hover,.btn.disabled,.btn.disabled:hover{color:rgba(102,102,102,0.5);cursor:default;background-color:rgba(229,229,229,0.5);background-image:none;box-shadow:none}.btn-outline{color:#7253ed;background:transparent;box-shadow:inset 0 0 0 2px #e6e1e8}.btn-outline:hover,.btn-outline:active,.btn-outline.zeroclipboard-is-hover,.btn-outline.zeroclipboard-is-active{color:#6341eb;text-decoration:none;background-color:transparent;box-shadow:inset 0 0 0 3px #e6e1e8}.btn-outline:focus{text-decoration:none;outline:none;box-shadow:inset 0 0 0 2px #5c5962,0 0 0 3px rgba(0,0,255,0.25)}.btn-outline:focus:hover,.btn-outline.selected:focus{box-shadow:inset 0 0 0 2px #5c5962}.btn-primary{color:#fff;background-color:#5739ce;background-image:linear-gradient(#6f55d5, #5739ce);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-primary:hover,.btn-primary.zeroclipboard-is-hover{color:#fff;background-color:#5132cb;background-image:linear-gradient(#6549d2,#5132cb)}.btn-primary:active,.btn-primary.selected,.btn-primary.zeroclipboard-is-active{background-color:#4f31c6;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-primary.selected:hover{background-color:#472cb2}.btn-purple{color:#fff;background-color:#5739ce;background-image:linear-gradient(#6f55d5, #5739ce);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-purple:hover,.btn-purple.zeroclipboard-is-hover{color:#fff;background-color:#5132cb;background-image:linear-gradient(#6549d2,#5132cb)}.btn-purple:active,.btn-purple.selected,.btn-purple.zeroclipboard-is-active{background-color:#4f31c6;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-purple.selected:hover{background-color:#472cb2}.btn-blue{color:#fff;background-color:#227efa;background-image:linear-gradient(#4593fb, #227efa);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-blue:hover,.btn-blue.zeroclipboard-is-hover{color:#fff;background-color:#1878fa;background-image:linear-gradient(#368afa,#1878fa)}.btn-blue:active,.btn-blue.selected,.btn-blue.zeroclipboard-is-active{background-color:#1375f9;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-blue.selected:hover{background-color:#0669ed}.btn-green{color:#fff;background-color:#10ac7d;background-image:linear-gradient(#13cc95, #10ac7d);box-shadow:0 1px 3px rgba(0,0,0,0.25),0 4px 10px rgba(0,0,0,0.12)}.btn-green:hover,.btn-green.zeroclipboard-is-hover{color:#fff;background-color:#0fa276;background-image:linear-gradient(#12be8b,#0fa276)}.btn-green:active,.btn-green.selected,.btn-green.zeroclipboard-is-active{background-color:#0f9e73;background-image:none;box-shadow:inset 0 2px 4px rgba(0,0,0,0.15)}.btn-green.selected:hover{background-color:#0d8662}.search{position:relative;z-index:2;flex-grow:1;height:4rem;padding:.5rem;transition:padding linear 200ms}@media (min-width: 50rem){.search{position:relative !important;width:auto !important;height:100% !important;padding:0;transition:none}}.search-input-wrap{position:relative;z-index:1;height:3rem;overflow:hidden;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);transition:height linear 200ms}@media (min-width: 50rem){.search-input-wrap{position:absolute;width:100%;max-width:536px;height:100% !important;border-radius:0;box-shadow:none;transition:width ease 400ms}}.search-input{position:absolute;width:100%;height:100%;padding:.5rem 1rem .5rem 2.5rem;font-size:16px;color:#5c5962;background-color:#fff;border-top:0;border-right:0;border-bottom:0;border-left:0;border-radius:0}@media (min-width: 50rem){.search-input{padding:.5rem 1rem .5rem 3.5rem;font-size:14px;background-color:#fff;transition:padding-left linear 200ms}}.search-input:focus{outline:0}.search-input:focus+.search-label .search-icon{color:#7253ed}.search-label{position:absolute;display:flex;height:100%;padding-left:1rem}@media (min-width: 50rem){.search-label{padding-left:2rem;transition:padding-left linear 200ms}}.search-label .search-icon{width:1.2rem;height:1.2rem;align-self:center;color:#959396}.search-results{position:absolute;left:0;display:none;width:100%;max-height:calc(100% - 4rem);overflow-y:auto;background-color:#fff;border-bottom-right-radius:4px;border-bottom-left-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}@media (min-width: 50rem){.search-results{top:100%;width:536px;max-height:calc(100vh - 200%) !important}}.search-results-list{padding-left:0;margin-bottom:.25rem;list-style:none;font-size:14px !important}@media (min-width: 31.25rem){.search-results-list{font-size:16px !important}}@media (min-width: 50rem){.search-results-list{font-size:12px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.search-results-list{font-size:14px !important}}.search-results-list-item{padding:0;margin:0}.search-result{display:block;padding:.25rem .75rem}.search-result:hover,.search-result.active{background-color:#ebedf5}.search-result-title{display:block;padding-top:.5rem;padding-bottom:.5rem}@media (min-width: 31.25rem){.search-result-title{display:inline-block;width:40%;padding-right:.5rem;vertical-align:top}}.search-result-doc{display:flex;align-items:center;word-wrap:break-word}.search-result-doc.search-result-doc-parent{opacity:0.5;font-size:12px !important}@media (min-width: 31.25rem){.search-result-doc.search-result-doc-parent{font-size:14px !important}}@media (min-width: 50rem){.search-result-doc.search-result-doc-parent{font-size:11px !important}}@media (min-width: 50rem) and (min-width: 31.25rem){.search-result-doc.search-result-doc-parent{font-size:12px !important}}.search-result-doc .search-result-icon{width:1rem;height:1rem;margin-right:.5rem;color:#7253ed;flex-shrink:0}.search-result-doc .search-result-doc-title{overflow:auto}.search-result-section{margin-left:1.5rem;word-wrap:break-word}.search-result-rel-url{display:block;margin-left:1.5rem;overflow:hidden;color:#959396;text-overflow:ellipsis;white-space:nowrap;font-size:9px !important}@media (min-width: 31.25rem){.search-result-rel-url{font-size:10px !important}}.search-result-previews{display:block;padding-top:.5rem;padding-bottom:.5rem;padding-left:1rem;margin-left:.5rem;color:#959396;word-wrap:break-word;border-left:1px solid;border-left-color:#eeebee;font-size:11px !important}@media (min-width: 31.25rem){.search-result-previews{font-size:12px !important}}@media (min-width: 31.25rem){.search-result-previews{display:inline-block;width:60%;padding-left:.5rem;margin-left:0;vertical-align:top}}.search-result-preview+.search-result-preview{margin-top:.25rem}.search-result-highlight{font-weight:bold}.search-no-result{padding:.5rem .75rem;font-size:12px !important}@media (min-width: 31.25rem){.search-no-result{font-size:14px !important}}.search-button{position:fixed;right:1rem;bottom:1rem;display:flex;width:3.5rem;height:3.5rem;background-color:#fff;border:1px solid rgba(114,83,237,0.3);border-radius:1.75rem;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08);align-items:center;justify-content:center}.search-overlay{position:fixed;top:0;left:0;z-index:1;width:0;height:0;background-color:rgba(0,0,0,0.3);opacity:0;transition:opacity ease 400ms,width 0s 400ms,height 0s 400ms}.search-active .search{position:fixed;top:0;left:0;width:100%;height:100%;padding:0}.search-active .search-input-wrap{height:4rem;border-radius:0}@media (min-width: 50rem){.search-active .search-input-wrap{width:536px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}}.search-active .search-input{background-color:#fff}@media (min-width: 50rem){.search-active .search-input{padding-left:2.3rem}}@media (min-width: 50rem){.search-active .search-label{padding-left:0.6rem}}.search-active .search-results{display:block}.search-active .search-overlay{width:100%;height:100%;opacity:1;transition:opacity ease 400ms,width 0s,height 0s}@media (min-width: 50rem){.search-active .main{position:fixed;right:0;left:0}}.search-active .main-header{padding-top:4rem}@media (min-width: 50rem){.search-active .main-header{padding-top:0}}.table-wrapper{display:block;width:100%;max-width:100%;margin-bottom:1.5rem;overflow-x:auto;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,0.12),0 3px 10px rgba(0,0,0,0.08)}table{display:table;min-width:100%;border-collapse:separate}th,td{font-size:12px !important;min-width:120px;padding:.5rem .75rem;background-color:#fff;border-bottom:1px solid rgba(238,235,238,0.5);border-left:1px solid #eeebee}@media (min-width: 31.25rem){th,td{font-size:14px !important}}th:first-of-type,td:first-of-type{border-left:0}tbody tr:last-of-type th,tbody tr:last-of-type td{border-bottom:0}tbody tr:last-of-type td{padding-bottom:.75rem}thead th{border-bottom:1px solid #eeebee}:not(pre,figure)>code{padding:0.2em 0.15em;font-weight:400;background-color:#f5f6fa;border:1px solid #eeebee;border-radius:4px}a:visited code{border-color:#eeebee}div.highlighter-rouge,div.listingblock>div.content,figure.highlight{margin-top:0;margin-bottom:.75rem;background-color:#f5f6fa;border-radius:4px;box-shadow:none;-webkit-overflow-scrolling:touch;position:relative;padding:0}div.highlighter-rouge>button,div.listingblock>div.content>button,figure.highlight>button{width:.75rem;opacity:0;position:absolute;top:0;right:0;border:.75rem solid #f5f6fa;background-color:#f5f6fa;color:#5c5962;box-sizing:content-box}div.highlighter-rouge>button svg,div.listingblock>div.content>button svg,figure.highlight>button svg{fill:#5c5962}div.highlighter-rouge>button:active,div.listingblock>div.content>button:active,figure.highlight>button:active{text-decoration:none;outline:none;opacity:1}div.highlighter-rouge>button:focus,div.listingblock>div.content>button:focus,figure.highlight>button:focus{opacity:1}div.highlighter-rouge:hover>button,div.listingblock>div.content:hover>button,figure.highlight:hover>button{cursor:copy;opacity:1}div.highlighter-rouge div.highlight{overflow-x:auto;padding:.75rem;margin:0;border:0}div.highlighter-rouge pre.highlight,div.highlighter-rouge code{padding:0;margin:0;border:0}div.listingblock{margin-top:0;margin-bottom:.75rem}div.listingblock div.content{overflow-x:auto;padding:.75rem;margin:0;border:0}div.listingblock div.content>pre,div.listingblock code{padding:0;margin:0;border:0}figure.highlight pre,figure.highlight :not(pre)>code{overflow-x:auto;padding:.75rem;margin:0;border:0}.highlight .table-wrapper{padding:.75rem 0;margin:0;border:0;box-shadow:none}.highlight .table-wrapper td,.highlight .table-wrapper pre{font-size:11px !important;min-width:0;padding:0;background-color:#f5f6fa;border:0}@media (min-width: 31.25rem){.highlight .table-wrapper td,.highlight .table-wrapper pre{font-size:12px !important}}.highlight .table-wrapper td.gl{width:1em;padding-right:.75rem;padding-left:.75rem}.highlight .table-wrapper pre{margin:0;line-height:2}.code-example,.listingblock>.title{padding:.75rem;margin-bottom:.75rem;overflow:auto;border:1px solid #eeebee;border-radius:4px}.code-example+.highlighter-rouge,.code-example+.sectionbody .listingblock,.code-example+.content,.code-example+figure.highlight,.listingblock>.title+.highlighter-rouge,.listingblock>.title+.sectionbody .listingblock,.listingblock>.title+.content,.listingblock>.title+figure.highlight{position:relative;margin-top:-1rem;border-right:1px solid #eeebee;border-bottom:1px solid #eeebee;border-left:1px solid #eeebee;border-top-left-radius:0;border-top-right-radius:0}code.language-mermaid{padding:0;background-color:inherit;border:0}.highlight,pre.highlight{background:#f5f6fa;color:#5c5962}.highlight pre{background:#f5f6fa}.text-grey-dk-000{color:#959396 !important}.text-grey-dk-100{color:#5c5962 !important}.text-grey-dk-200{color:#44434d !important}.text-grey-dk-250{color:#302d36 !important}.text-grey-dk-300{color:#27262b !important}.text-grey-lt-000{color:#f5f6fa !important}.text-grey-lt-100{color:#eeebee !important}.text-grey-lt-200{color:#ecebed !important}.text-grey-lt-300{color:#e6e1e8 !important}.text-blue-000{color:#2c84fa !important}.text-blue-100{color:#2869e6 !important}.text-blue-200{color:#264caf !important}.text-blue-300{color:#183385 !important}.text-green-000{color:#41d693 !important}.text-green-100{color:#11b584 !important}.text-green-200{color:#009c7b !important}.text-green-300{color:#026e57 !important}.text-purple-000{color:#7253ed !important}.text-purple-100{color:#5e41d0 !important}.text-purple-200{color:#4e26af !important}.text-purple-300{color:#381885 !important}.text-yellow-000{color:#ffeb82 !important}.text-yellow-100{color:#fadf50 !important}.text-yellow-200{color:#f7d12e !important}.text-yellow-300{color:#e7af06 !important}.text-red-000{color:#f77e7e !important}.text-red-100{color:#f96e65 !important}.text-red-200{color:#e94c4c !important}.text-red-300{color:#dd2e2e !important}.bg-grey-dk-000{background-color:#959396 !important}.bg-grey-dk-100{background-color:#5c5962 !important}.bg-grey-dk-200{background-color:#44434d !important}.bg-grey-dk-250{background-color:#302d36 !important}.bg-grey-dk-300{background-color:#27262b !important}.bg-grey-lt-000{background-color:#f5f6fa !important}.bg-grey-lt-100{background-color:#eeebee !important}.bg-grey-lt-200{background-color:#ecebed !important}.bg-grey-lt-300{background-color:#e6e1e8 !important}.bg-blue-000{background-color:#2c84fa !important}.bg-blue-100{background-color:#2869e6 !important}.bg-blue-200{background-color:#264caf !important}.bg-blue-300{background-color:#183385 !important}.bg-green-000{background-color:#41d693 !important}.bg-green-100{background-color:#11b584 !important}.bg-green-200{background-color:#009c7b !important}.bg-green-300{background-color:#026e57 !important}.bg-purple-000{background-color:#7253ed !important}.bg-purple-100{background-color:#5e41d0 !important}.bg-purple-200{background-color:#4e26af !important}.bg-purple-300{background-color:#381885 !important}.bg-yellow-000{background-color:#ffeb82 !important}.bg-yellow-100{background-color:#fadf50 !important}.bg-yellow-200{background-color:#f7d12e !important}.bg-yellow-300{background-color:#e7af06 !important}.bg-red-000{background-color:#f77e7e !important}.bg-red-100{background-color:#f96e65 !important}.bg-red-200{background-color:#e94c4c !important}.bg-red-300{background-color:#dd2e2e !important}.d-block{display:block !important}.d-flex{display:flex !important}.d-inline{display:inline !important}.d-inline-block{display:inline-block !important}.d-none{display:none !important}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 20rem){.d-xs-block{display:block !important}.d-xs-flex{display:flex !important}.d-xs-inline{display:inline !important}.d-xs-inline-block{display:inline-block !important}.d-xs-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 31.25rem){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 50rem){.d-md-block{display:block !important}.d-md-flex{display:flex !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 66.5rem){.d-lg-block{display:block !important}.d-lg-flex{display:flex !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}@media (min-width: 87.5rem){.d-xl-block{display:block !important}.d-xl-flex{display:flex !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-none{display:none !important}}.float-left{float:left !important}.float-right{float:right !important}.flex-justify-start{justify-content:flex-start !important}.flex-justify-end{justify-content:flex-end !important}.flex-justify-between{justify-content:space-between !important}.flex-justify-around{justify-content:space-around !important}.v-align-baseline{vertical-align:baseline !important}.v-align-bottom{vertical-align:bottom !important}.v-align-middle{vertical-align:middle !important}.v-align-text-bottom{vertical-align:text-bottom !important}.v-align-text-top{vertical-align:text-top !important}.v-align-top{vertical-align:top !important}.fs-1{font-size:9px !important}@media (min-width: 31.25rem){.fs-1{font-size:10px !important}}.fs-2{font-size:11px !important}@media (min-width: 31.25rem){.fs-2{font-size:12px !important}}.fs-3{font-size:12px !important}@media (min-width: 31.25rem){.fs-3{font-size:14px !important}}.fs-4{font-size:14px !important}@media (min-width: 31.25rem){.fs-4{font-size:16px !important}}.fs-5{font-size:16px !important}@media (min-width: 31.25rem){.fs-5{font-size:18px !important}}.fs-6{font-size:18px !important}@media (min-width: 31.25rem){.fs-6{font-size:24px !important;line-height:1.25}}.fs-7{font-size:24px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-7{font-size:32px !important}}.fs-8{font-size:32px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-8{font-size:36px !important}}.fs-9{font-size:36px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-9{font-size:42px !important}}.fs-10{font-size:42px !important;line-height:1.25}@media (min-width: 31.25rem){.fs-10{font-size:48px !important}}.fw-300{font-weight:300 !important}.fw-400{font-weight:400 !important}.fw-500{font-weight:500 !important}.fw-700{font-weight:700 !important}.lh-0{line-height:0 !important}.lh-default{line-height:1.4}.lh-tight{line-height:1.25}.ls-5{letter-spacing:0.05em !important}.ls-10{letter-spacing:0.1em !important}.ls-0{letter-spacing:0 !important}.text-uppercase{text-transform:uppercase !important}.list-style-none{padding:0 !important;margin:0 !important;list-style:none !important}.list-style-none li::before{display:none !important}.mx-auto{margin-right:auto !important;margin-left:auto !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-right:0 !important;margin-left:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-0{margin-right:-0 !important;margin-left:-0 !important}.mx-0-auto{margin-right:auto !important;margin-left:auto !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-1{margin-right:-.25rem !important;margin-left:-.25rem !important}.mx-1-auto{margin-right:auto !important;margin-left:auto !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-2{margin-right:-.5rem !important;margin-left:-.5rem !important}.mx-2-auto{margin-right:auto !important;margin-left:auto !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-3{margin-right:-.75rem !important;margin-left:-.75rem !important}.mx-3-auto{margin-right:auto !important;margin-left:auto !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-right:1rem !important;margin-left:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-4{margin-right:-1rem !important;margin-left:-1rem !important}.mx-4-auto{margin-right:auto !important;margin-left:auto !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}.mx-5-auto{margin-right:auto !important;margin-left:auto !important}.m-6{margin:2rem !important}.mt-6{margin-top:2rem !important}.mr-6{margin-right:2rem !important}.mb-6{margin-bottom:2rem !important}.ml-6{margin-left:2rem !important}.mx-6{margin-right:2rem !important;margin-left:2rem !important}.my-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-6{margin-right:-2rem !important;margin-left:-2rem !important}.mx-6-auto{margin-right:auto !important;margin-left:auto !important}.m-7{margin:2.5rem !important}.mt-7{margin-top:2.5rem !important}.mr-7{margin-right:2.5rem !important}.mb-7{margin-bottom:2.5rem !important}.ml-7{margin-left:2.5rem !important}.mx-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}.mx-7-auto{margin-right:auto !important;margin-left:auto !important}.m-8{margin:3rem !important}.mt-8{margin-top:3rem !important}.mr-8{margin-right:3rem !important}.mb-8{margin-bottom:3rem !important}.ml-8{margin-left:3rem !important}.mx-8{margin-right:3rem !important;margin-left:3rem !important}.my-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-8{margin-right:-3rem !important;margin-left:-3rem !important}.mx-8-auto{margin-right:auto !important;margin-left:auto !important}.m-9{margin:3.5rem !important}.mt-9{margin-top:3.5rem !important}.mr-9{margin-right:3.5rem !important}.mb-9{margin-bottom:3.5rem !important}.ml-9{margin-left:3.5rem !important}.mx-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}.mx-9-auto{margin-right:auto !important;margin-left:auto !important}.m-10{margin:4rem !important}.mt-10{margin-top:4rem !important}.mr-10{margin-right:4rem !important}.mb-10{margin-bottom:4rem !important}.ml-10{margin-left:4rem !important}.mx-10{margin-right:4rem !important;margin-left:4rem !important}.my-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-10{margin-right:-4rem !important;margin-left:-4rem !important}.mx-10-auto{margin-right:auto !important;margin-left:auto !important}@media (min-width: 20rem){.m-xs-0{margin:0 !important}.mt-xs-0{margin-top:0 !important}.mr-xs-0{margin-right:0 !important}.mb-xs-0{margin-bottom:0 !important}.ml-xs-0{margin-left:0 !important}.mx-xs-0{margin-right:0 !important;margin-left:0 !important}.my-xs-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-xs-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 20rem){.m-xs-1{margin:.25rem !important}.mt-xs-1{margin-top:.25rem !important}.mr-xs-1{margin-right:.25rem !important}.mb-xs-1{margin-bottom:.25rem !important}.ml-xs-1{margin-left:.25rem !important}.mx-xs-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-xs-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-xs-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 20rem){.m-xs-2{margin:.5rem !important}.mt-xs-2{margin-top:.5rem !important}.mr-xs-2{margin-right:.5rem !important}.mb-xs-2{margin-bottom:.5rem !important}.ml-xs-2{margin-left:.5rem !important}.mx-xs-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-xs-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-xs-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 20rem){.m-xs-3{margin:.75rem !important}.mt-xs-3{margin-top:.75rem !important}.mr-xs-3{margin-right:.75rem !important}.mb-xs-3{margin-bottom:.75rem !important}.ml-xs-3{margin-left:.75rem !important}.mx-xs-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-xs-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-xs-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 20rem){.m-xs-4{margin:1rem !important}.mt-xs-4{margin-top:1rem !important}.mr-xs-4{margin-right:1rem !important}.mb-xs-4{margin-bottom:1rem !important}.ml-xs-4{margin-left:1rem !important}.mx-xs-4{margin-right:1rem !important;margin-left:1rem !important}.my-xs-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-xs-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 20rem){.m-xs-5{margin:1.5rem !important}.mt-xs-5{margin-top:1.5rem !important}.mr-xs-5{margin-right:1.5rem !important}.mb-xs-5{margin-bottom:1.5rem !important}.ml-xs-5{margin-left:1.5rem !important}.mx-xs-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-xs-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-xs-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 20rem){.m-xs-6{margin:2rem !important}.mt-xs-6{margin-top:2rem !important}.mr-xs-6{margin-right:2rem !important}.mb-xs-6{margin-bottom:2rem !important}.ml-xs-6{margin-left:2rem !important}.mx-xs-6{margin-right:2rem !important;margin-left:2rem !important}.my-xs-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-xs-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 20rem){.m-xs-7{margin:2.5rem !important}.mt-xs-7{margin-top:2.5rem !important}.mr-xs-7{margin-right:2.5rem !important}.mb-xs-7{margin-bottom:2.5rem !important}.ml-xs-7{margin-left:2.5rem !important}.mx-xs-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-xs-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-xs-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 20rem){.m-xs-8{margin:3rem !important}.mt-xs-8{margin-top:3rem !important}.mr-xs-8{margin-right:3rem !important}.mb-xs-8{margin-bottom:3rem !important}.ml-xs-8{margin-left:3rem !important}.mx-xs-8{margin-right:3rem !important;margin-left:3rem !important}.my-xs-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-xs-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 20rem){.m-xs-9{margin:3.5rem !important}.mt-xs-9{margin-top:3.5rem !important}.mr-xs-9{margin-right:3.5rem !important}.mb-xs-9{margin-bottom:3.5rem !important}.ml-xs-9{margin-left:3.5rem !important}.mx-xs-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-xs-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-xs-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 20rem){.m-xs-10{margin:4rem !important}.mt-xs-10{margin-top:4rem !important}.mr-xs-10{margin-right:4rem !important}.mb-xs-10{margin-bottom:4rem !important}.ml-xs-10{margin-left:4rem !important}.mx-xs-10{margin-right:4rem !important;margin-left:4rem !important}.my-xs-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-xs-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 31.25rem){.m-sm-0{margin:0 !important}.mt-sm-0{margin-top:0 !important}.mr-sm-0{margin-right:0 !important}.mb-sm-0{margin-bottom:0 !important}.ml-sm-0{margin-left:0 !important}.mx-sm-0{margin-right:0 !important;margin-left:0 !important}.my-sm-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-sm-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 31.25rem){.m-sm-1{margin:.25rem !important}.mt-sm-1{margin-top:.25rem !important}.mr-sm-1{margin-right:.25rem !important}.mb-sm-1{margin-bottom:.25rem !important}.ml-sm-1{margin-left:.25rem !important}.mx-sm-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-sm-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-sm-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 31.25rem){.m-sm-2{margin:.5rem !important}.mt-sm-2{margin-top:.5rem !important}.mr-sm-2{margin-right:.5rem !important}.mb-sm-2{margin-bottom:.5rem !important}.ml-sm-2{margin-left:.5rem !important}.mx-sm-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-sm-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-sm-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 31.25rem){.m-sm-3{margin:.75rem !important}.mt-sm-3{margin-top:.75rem !important}.mr-sm-3{margin-right:.75rem !important}.mb-sm-3{margin-bottom:.75rem !important}.ml-sm-3{margin-left:.75rem !important}.mx-sm-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-sm-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-sm-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 31.25rem){.m-sm-4{margin:1rem !important}.mt-sm-4{margin-top:1rem !important}.mr-sm-4{margin-right:1rem !important}.mb-sm-4{margin-bottom:1rem !important}.ml-sm-4{margin-left:1rem !important}.mx-sm-4{margin-right:1rem !important;margin-left:1rem !important}.my-sm-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-sm-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 31.25rem){.m-sm-5{margin:1.5rem !important}.mt-sm-5{margin-top:1.5rem !important}.mr-sm-5{margin-right:1.5rem !important}.mb-sm-5{margin-bottom:1.5rem !important}.ml-sm-5{margin-left:1.5rem !important}.mx-sm-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-sm-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-sm-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 31.25rem){.m-sm-6{margin:2rem !important}.mt-sm-6{margin-top:2rem !important}.mr-sm-6{margin-right:2rem !important}.mb-sm-6{margin-bottom:2rem !important}.ml-sm-6{margin-left:2rem !important}.mx-sm-6{margin-right:2rem !important;margin-left:2rem !important}.my-sm-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-sm-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 31.25rem){.m-sm-7{margin:2.5rem !important}.mt-sm-7{margin-top:2.5rem !important}.mr-sm-7{margin-right:2.5rem !important}.mb-sm-7{margin-bottom:2.5rem !important}.ml-sm-7{margin-left:2.5rem !important}.mx-sm-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-sm-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-sm-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 31.25rem){.m-sm-8{margin:3rem !important}.mt-sm-8{margin-top:3rem !important}.mr-sm-8{margin-right:3rem !important}.mb-sm-8{margin-bottom:3rem !important}.ml-sm-8{margin-left:3rem !important}.mx-sm-8{margin-right:3rem !important;margin-left:3rem !important}.my-sm-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-sm-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 31.25rem){.m-sm-9{margin:3.5rem !important}.mt-sm-9{margin-top:3.5rem !important}.mr-sm-9{margin-right:3.5rem !important}.mb-sm-9{margin-bottom:3.5rem !important}.ml-sm-9{margin-left:3.5rem !important}.mx-sm-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-sm-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-sm-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 31.25rem){.m-sm-10{margin:4rem !important}.mt-sm-10{margin-top:4rem !important}.mr-sm-10{margin-right:4rem !important}.mb-sm-10{margin-bottom:4rem !important}.ml-sm-10{margin-left:4rem !important}.mx-sm-10{margin-right:4rem !important;margin-left:4rem !important}.my-sm-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-sm-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 50rem){.m-md-0{margin:0 !important}.mt-md-0{margin-top:0 !important}.mr-md-0{margin-right:0 !important}.mb-md-0{margin-bottom:0 !important}.ml-md-0{margin-left:0 !important}.mx-md-0{margin-right:0 !important;margin-left:0 !important}.my-md-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-md-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 50rem){.m-md-1{margin:.25rem !important}.mt-md-1{margin-top:.25rem !important}.mr-md-1{margin-right:.25rem !important}.mb-md-1{margin-bottom:.25rem !important}.ml-md-1{margin-left:.25rem !important}.mx-md-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-md-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-md-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 50rem){.m-md-2{margin:.5rem !important}.mt-md-2{margin-top:.5rem !important}.mr-md-2{margin-right:.5rem !important}.mb-md-2{margin-bottom:.5rem !important}.ml-md-2{margin-left:.5rem !important}.mx-md-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-md-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-md-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 50rem){.m-md-3{margin:.75rem !important}.mt-md-3{margin-top:.75rem !important}.mr-md-3{margin-right:.75rem !important}.mb-md-3{margin-bottom:.75rem !important}.ml-md-3{margin-left:.75rem !important}.mx-md-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-md-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-md-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 50rem){.m-md-4{margin:1rem !important}.mt-md-4{margin-top:1rem !important}.mr-md-4{margin-right:1rem !important}.mb-md-4{margin-bottom:1rem !important}.ml-md-4{margin-left:1rem !important}.mx-md-4{margin-right:1rem !important;margin-left:1rem !important}.my-md-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-md-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 50rem){.m-md-5{margin:1.5rem !important}.mt-md-5{margin-top:1.5rem !important}.mr-md-5{margin-right:1.5rem !important}.mb-md-5{margin-bottom:1.5rem !important}.ml-md-5{margin-left:1.5rem !important}.mx-md-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-md-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-md-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 50rem){.m-md-6{margin:2rem !important}.mt-md-6{margin-top:2rem !important}.mr-md-6{margin-right:2rem !important}.mb-md-6{margin-bottom:2rem !important}.ml-md-6{margin-left:2rem !important}.mx-md-6{margin-right:2rem !important;margin-left:2rem !important}.my-md-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-md-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 50rem){.m-md-7{margin:2.5rem !important}.mt-md-7{margin-top:2.5rem !important}.mr-md-7{margin-right:2.5rem !important}.mb-md-7{margin-bottom:2.5rem !important}.ml-md-7{margin-left:2.5rem !important}.mx-md-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-md-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-md-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 50rem){.m-md-8{margin:3rem !important}.mt-md-8{margin-top:3rem !important}.mr-md-8{margin-right:3rem !important}.mb-md-8{margin-bottom:3rem !important}.ml-md-8{margin-left:3rem !important}.mx-md-8{margin-right:3rem !important;margin-left:3rem !important}.my-md-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-md-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 50rem){.m-md-9{margin:3.5rem !important}.mt-md-9{margin-top:3.5rem !important}.mr-md-9{margin-right:3.5rem !important}.mb-md-9{margin-bottom:3.5rem !important}.ml-md-9{margin-left:3.5rem !important}.mx-md-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-md-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-md-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 50rem){.m-md-10{margin:4rem !important}.mt-md-10{margin-top:4rem !important}.mr-md-10{margin-right:4rem !important}.mb-md-10{margin-bottom:4rem !important}.ml-md-10{margin-left:4rem !important}.mx-md-10{margin-right:4rem !important;margin-left:4rem !important}.my-md-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-md-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 66.5rem){.m-lg-0{margin:0 !important}.mt-lg-0{margin-top:0 !important}.mr-lg-0{margin-right:0 !important}.mb-lg-0{margin-bottom:0 !important}.ml-lg-0{margin-left:0 !important}.mx-lg-0{margin-right:0 !important;margin-left:0 !important}.my-lg-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-lg-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 66.5rem){.m-lg-1{margin:.25rem !important}.mt-lg-1{margin-top:.25rem !important}.mr-lg-1{margin-right:.25rem !important}.mb-lg-1{margin-bottom:.25rem !important}.ml-lg-1{margin-left:.25rem !important}.mx-lg-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-lg-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-lg-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 66.5rem){.m-lg-2{margin:.5rem !important}.mt-lg-2{margin-top:.5rem !important}.mr-lg-2{margin-right:.5rem !important}.mb-lg-2{margin-bottom:.5rem !important}.ml-lg-2{margin-left:.5rem !important}.mx-lg-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-lg-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-lg-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 66.5rem){.m-lg-3{margin:.75rem !important}.mt-lg-3{margin-top:.75rem !important}.mr-lg-3{margin-right:.75rem !important}.mb-lg-3{margin-bottom:.75rem !important}.ml-lg-3{margin-left:.75rem !important}.mx-lg-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-lg-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-lg-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 66.5rem){.m-lg-4{margin:1rem !important}.mt-lg-4{margin-top:1rem !important}.mr-lg-4{margin-right:1rem !important}.mb-lg-4{margin-bottom:1rem !important}.ml-lg-4{margin-left:1rem !important}.mx-lg-4{margin-right:1rem !important;margin-left:1rem !important}.my-lg-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-lg-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 66.5rem){.m-lg-5{margin:1.5rem !important}.mt-lg-5{margin-top:1.5rem !important}.mr-lg-5{margin-right:1.5rem !important}.mb-lg-5{margin-bottom:1.5rem !important}.ml-lg-5{margin-left:1.5rem !important}.mx-lg-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-lg-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-lg-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 66.5rem){.m-lg-6{margin:2rem !important}.mt-lg-6{margin-top:2rem !important}.mr-lg-6{margin-right:2rem !important}.mb-lg-6{margin-bottom:2rem !important}.ml-lg-6{margin-left:2rem !important}.mx-lg-6{margin-right:2rem !important;margin-left:2rem !important}.my-lg-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-lg-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 66.5rem){.m-lg-7{margin:2.5rem !important}.mt-lg-7{margin-top:2.5rem !important}.mr-lg-7{margin-right:2.5rem !important}.mb-lg-7{margin-bottom:2.5rem !important}.ml-lg-7{margin-left:2.5rem !important}.mx-lg-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-lg-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-lg-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 66.5rem){.m-lg-8{margin:3rem !important}.mt-lg-8{margin-top:3rem !important}.mr-lg-8{margin-right:3rem !important}.mb-lg-8{margin-bottom:3rem !important}.ml-lg-8{margin-left:3rem !important}.mx-lg-8{margin-right:3rem !important;margin-left:3rem !important}.my-lg-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-lg-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 66.5rem){.m-lg-9{margin:3.5rem !important}.mt-lg-9{margin-top:3.5rem !important}.mr-lg-9{margin-right:3.5rem !important}.mb-lg-9{margin-bottom:3.5rem !important}.ml-lg-9{margin-left:3.5rem !important}.mx-lg-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-lg-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-lg-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 66.5rem){.m-lg-10{margin:4rem !important}.mt-lg-10{margin-top:4rem !important}.mr-lg-10{margin-right:4rem !important}.mb-lg-10{margin-bottom:4rem !important}.ml-lg-10{margin-left:4rem !important}.mx-lg-10{margin-right:4rem !important;margin-left:4rem !important}.my-lg-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-lg-10{margin-right:-4rem !important;margin-left:-4rem !important}}@media (min-width: 87.5rem){.m-xl-0{margin:0 !important}.mt-xl-0{margin-top:0 !important}.mr-xl-0{margin-right:0 !important}.mb-xl-0{margin-bottom:0 !important}.ml-xl-0{margin-left:0 !important}.mx-xl-0{margin-right:0 !important;margin-left:0 !important}.my-xl-0{margin-top:0 !important;margin-bottom:0 !important}.mxn-xl-0{margin-right:-0 !important;margin-left:-0 !important}}@media (min-width: 87.5rem){.m-xl-1{margin:.25rem !important}.mt-xl-1{margin-top:.25rem !important}.mr-xl-1{margin-right:.25rem !important}.mb-xl-1{margin-bottom:.25rem !important}.ml-xl-1{margin-left:.25rem !important}.mx-xl-1{margin-right:.25rem !important;margin-left:.25rem !important}.my-xl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.mxn-xl-1{margin-right:-.25rem !important;margin-left:-.25rem !important}}@media (min-width: 87.5rem){.m-xl-2{margin:.5rem !important}.mt-xl-2{margin-top:.5rem !important}.mr-xl-2{margin-right:.5rem !important}.mb-xl-2{margin-bottom:.5rem !important}.ml-xl-2{margin-left:.5rem !important}.mx-xl-2{margin-right:.5rem !important;margin-left:.5rem !important}.my-xl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.mxn-xl-2{margin-right:-.5rem !important;margin-left:-.5rem !important}}@media (min-width: 87.5rem){.m-xl-3{margin:.75rem !important}.mt-xl-3{margin-top:.75rem !important}.mr-xl-3{margin-right:.75rem !important}.mb-xl-3{margin-bottom:.75rem !important}.ml-xl-3{margin-left:.75rem !important}.mx-xl-3{margin-right:.75rem !important;margin-left:.75rem !important}.my-xl-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.mxn-xl-3{margin-right:-.75rem !important;margin-left:-.75rem !important}}@media (min-width: 87.5rem){.m-xl-4{margin:1rem !important}.mt-xl-4{margin-top:1rem !important}.mr-xl-4{margin-right:1rem !important}.mb-xl-4{margin-bottom:1rem !important}.ml-xl-4{margin-left:1rem !important}.mx-xl-4{margin-right:1rem !important;margin-left:1rem !important}.my-xl-4{margin-top:1rem !important;margin-bottom:1rem !important}.mxn-xl-4{margin-right:-1rem !important;margin-left:-1rem !important}}@media (min-width: 87.5rem){.m-xl-5{margin:1.5rem !important}.mt-xl-5{margin-top:1.5rem !important}.mr-xl-5{margin-right:1.5rem !important}.mb-xl-5{margin-bottom:1.5rem !important}.ml-xl-5{margin-left:1.5rem !important}.mx-xl-5{margin-right:1.5rem !important;margin-left:1.5rem !important}.my-xl-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.mxn-xl-5{margin-right:-1.5rem !important;margin-left:-1.5rem !important}}@media (min-width: 87.5rem){.m-xl-6{margin:2rem !important}.mt-xl-6{margin-top:2rem !important}.mr-xl-6{margin-right:2rem !important}.mb-xl-6{margin-bottom:2rem !important}.ml-xl-6{margin-left:2rem !important}.mx-xl-6{margin-right:2rem !important;margin-left:2rem !important}.my-xl-6{margin-top:2rem !important;margin-bottom:2rem !important}.mxn-xl-6{margin-right:-2rem !important;margin-left:-2rem !important}}@media (min-width: 87.5rem){.m-xl-7{margin:2.5rem !important}.mt-xl-7{margin-top:2.5rem !important}.mr-xl-7{margin-right:2.5rem !important}.mb-xl-7{margin-bottom:2.5rem !important}.ml-xl-7{margin-left:2.5rem !important}.mx-xl-7{margin-right:2.5rem !important;margin-left:2.5rem !important}.my-xl-7{margin-top:2.5rem !important;margin-bottom:2.5rem !important}.mxn-xl-7{margin-right:-2.5rem !important;margin-left:-2.5rem !important}}@media (min-width: 87.5rem){.m-xl-8{margin:3rem !important}.mt-xl-8{margin-top:3rem !important}.mr-xl-8{margin-right:3rem !important}.mb-xl-8{margin-bottom:3rem !important}.ml-xl-8{margin-left:3rem !important}.mx-xl-8{margin-right:3rem !important;margin-left:3rem !important}.my-xl-8{margin-top:3rem !important;margin-bottom:3rem !important}.mxn-xl-8{margin-right:-3rem !important;margin-left:-3rem !important}}@media (min-width: 87.5rem){.m-xl-9{margin:3.5rem !important}.mt-xl-9{margin-top:3.5rem !important}.mr-xl-9{margin-right:3.5rem !important}.mb-xl-9{margin-bottom:3.5rem !important}.ml-xl-9{margin-left:3.5rem !important}.mx-xl-9{margin-right:3.5rem !important;margin-left:3.5rem !important}.my-xl-9{margin-top:3.5rem !important;margin-bottom:3.5rem !important}.mxn-xl-9{margin-right:-3.5rem !important;margin-left:-3.5rem !important}}@media (min-width: 87.5rem){.m-xl-10{margin:4rem !important}.mt-xl-10{margin-top:4rem !important}.mr-xl-10{margin-right:4rem !important}.mb-xl-10{margin-bottom:4rem !important}.ml-xl-10{margin-left:4rem !important}.mx-xl-10{margin-right:4rem !important;margin-left:4rem !important}.my-xl-10{margin-top:4rem !important;margin-bottom:4rem !important}.mxn-xl-10{margin-right:-4rem !important;margin-left:-4rem !important}}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-right:0 !important;padding-left:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-right:1rem !important;padding-left:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:2rem !important}.pt-6{padding-top:2rem !important}.pr-6{padding-right:2rem !important}.pb-6{padding-bottom:2rem !important}.pl-6{padding-left:2rem !important}.px-6{padding-right:2rem !important;padding-left:2rem !important}.py-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-7{padding:2.5rem !important}.pt-7{padding-top:2.5rem !important}.pr-7{padding-right:2.5rem !important}.pb-7{padding-bottom:2.5rem !important}.pl-7{padding-left:2.5rem !important}.px-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-8{padding:3rem !important}.pt-8{padding-top:3rem !important}.pr-8{padding-right:3rem !important}.pb-8{padding-bottom:3rem !important}.pl-8{padding-left:3rem !important}.px-8{padding-right:3rem !important;padding-left:3rem !important}.py-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-9{padding:3.5rem !important}.pt-9{padding-top:3.5rem !important}.pr-9{padding-right:3.5rem !important}.pb-9{padding-bottom:3.5rem !important}.pl-9{padding-left:3.5rem !important}.px-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-10{padding:4rem !important}.pt-10{padding-top:4rem !important}.pr-10{padding-right:4rem !important}.pb-10{padding-bottom:4rem !important}.pl-10{padding-left:4rem !important}.px-10{padding-right:4rem !important;padding-left:4rem !important}.py-10{padding-top:4rem !important;padding-bottom:4rem !important}@media (min-width: 20rem){.p-xs-0{padding:0 !important}.pt-xs-0{padding-top:0 !important}.pr-xs-0{padding-right:0 !important}.pb-xs-0{padding-bottom:0 !important}.pl-xs-0{padding-left:0 !important}.px-xs-0{padding-right:0 !important;padding-left:0 !important}.py-xs-0{padding-top:0 !important;padding-bottom:0 !important}.p-xs-1{padding:.25rem !important}.pt-xs-1{padding-top:.25rem !important}.pr-xs-1{padding-right:.25rem !important}.pb-xs-1{padding-bottom:.25rem !important}.pl-xs-1{padding-left:.25rem !important}.px-xs-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-xs-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-xs-2{padding:.5rem !important}.pt-xs-2{padding-top:.5rem !important}.pr-xs-2{padding-right:.5rem !important}.pb-xs-2{padding-bottom:.5rem !important}.pl-xs-2{padding-left:.5rem !important}.px-xs-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-xs-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-xs-3{padding:.75rem !important}.pt-xs-3{padding-top:.75rem !important}.pr-xs-3{padding-right:.75rem !important}.pb-xs-3{padding-bottom:.75rem !important}.pl-xs-3{padding-left:.75rem !important}.px-xs-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-xs-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-xs-4{padding:1rem !important}.pt-xs-4{padding-top:1rem !important}.pr-xs-4{padding-right:1rem !important}.pb-xs-4{padding-bottom:1rem !important}.pl-xs-4{padding-left:1rem !important}.px-xs-4{padding-right:1rem !important;padding-left:1rem !important}.py-xs-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-xs-5{padding:1.5rem !important}.pt-xs-5{padding-top:1.5rem !important}.pr-xs-5{padding-right:1.5rem !important}.pb-xs-5{padding-bottom:1.5rem !important}.pl-xs-5{padding-left:1.5rem !important}.px-xs-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-xs-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-xs-6{padding:2rem !important}.pt-xs-6{padding-top:2rem !important}.pr-xs-6{padding-right:2rem !important}.pb-xs-6{padding-bottom:2rem !important}.pl-xs-6{padding-left:2rem !important}.px-xs-6{padding-right:2rem !important;padding-left:2rem !important}.py-xs-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-xs-7{padding:2.5rem !important}.pt-xs-7{padding-top:2.5rem !important}.pr-xs-7{padding-right:2.5rem !important}.pb-xs-7{padding-bottom:2.5rem !important}.pl-xs-7{padding-left:2.5rem !important}.px-xs-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-xs-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-xs-8{padding:3rem !important}.pt-xs-8{padding-top:3rem !important}.pr-xs-8{padding-right:3rem !important}.pb-xs-8{padding-bottom:3rem !important}.pl-xs-8{padding-left:3rem !important}.px-xs-8{padding-right:3rem !important;padding-left:3rem !important}.py-xs-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-xs-9{padding:3.5rem !important}.pt-xs-9{padding-top:3.5rem !important}.pr-xs-9{padding-right:3.5rem !important}.pb-xs-9{padding-bottom:3.5rem !important}.pl-xs-9{padding-left:3.5rem !important}.px-xs-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-xs-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-xs-10{padding:4rem !important}.pt-xs-10{padding-top:4rem !important}.pr-xs-10{padding-right:4rem !important}.pb-xs-10{padding-bottom:4rem !important}.pl-xs-10{padding-left:4rem !important}.px-xs-10{padding-right:4rem !important;padding-left:4rem !important}.py-xs-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 31.25rem){.p-sm-0{padding:0 !important}.pt-sm-0{padding-top:0 !important}.pr-sm-0{padding-right:0 !important}.pb-sm-0{padding-bottom:0 !important}.pl-sm-0{padding-left:0 !important}.px-sm-0{padding-right:0 !important;padding-left:0 !important}.py-sm-0{padding-top:0 !important;padding-bottom:0 !important}.p-sm-1{padding:.25rem !important}.pt-sm-1{padding-top:.25rem !important}.pr-sm-1{padding-right:.25rem !important}.pb-sm-1{padding-bottom:.25rem !important}.pl-sm-1{padding-left:.25rem !important}.px-sm-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-sm-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-sm-2{padding:.5rem !important}.pt-sm-2{padding-top:.5rem !important}.pr-sm-2{padding-right:.5rem !important}.pb-sm-2{padding-bottom:.5rem !important}.pl-sm-2{padding-left:.5rem !important}.px-sm-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-sm-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-sm-3{padding:.75rem !important}.pt-sm-3{padding-top:.75rem !important}.pr-sm-3{padding-right:.75rem !important}.pb-sm-3{padding-bottom:.75rem !important}.pl-sm-3{padding-left:.75rem !important}.px-sm-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-sm-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-sm-4{padding:1rem !important}.pt-sm-4{padding-top:1rem !important}.pr-sm-4{padding-right:1rem !important}.pb-sm-4{padding-bottom:1rem !important}.pl-sm-4{padding-left:1rem !important}.px-sm-4{padding-right:1rem !important;padding-left:1rem !important}.py-sm-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-sm-5{padding:1.5rem !important}.pt-sm-5{padding-top:1.5rem !important}.pr-sm-5{padding-right:1.5rem !important}.pb-sm-5{padding-bottom:1.5rem !important}.pl-sm-5{padding-left:1.5rem !important}.px-sm-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-sm-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-sm-6{padding:2rem !important}.pt-sm-6{padding-top:2rem !important}.pr-sm-6{padding-right:2rem !important}.pb-sm-6{padding-bottom:2rem !important}.pl-sm-6{padding-left:2rem !important}.px-sm-6{padding-right:2rem !important;padding-left:2rem !important}.py-sm-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-sm-7{padding:2.5rem !important}.pt-sm-7{padding-top:2.5rem !important}.pr-sm-7{padding-right:2.5rem !important}.pb-sm-7{padding-bottom:2.5rem !important}.pl-sm-7{padding-left:2.5rem !important}.px-sm-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-sm-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-sm-8{padding:3rem !important}.pt-sm-8{padding-top:3rem !important}.pr-sm-8{padding-right:3rem !important}.pb-sm-8{padding-bottom:3rem !important}.pl-sm-8{padding-left:3rem !important}.px-sm-8{padding-right:3rem !important;padding-left:3rem !important}.py-sm-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-sm-9{padding:3.5rem !important}.pt-sm-9{padding-top:3.5rem !important}.pr-sm-9{padding-right:3.5rem !important}.pb-sm-9{padding-bottom:3.5rem !important}.pl-sm-9{padding-left:3.5rem !important}.px-sm-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-sm-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-sm-10{padding:4rem !important}.pt-sm-10{padding-top:4rem !important}.pr-sm-10{padding-right:4rem !important}.pb-sm-10{padding-bottom:4rem !important}.pl-sm-10{padding-left:4rem !important}.px-sm-10{padding-right:4rem !important;padding-left:4rem !important}.py-sm-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 50rem){.p-md-0{padding:0 !important}.pt-md-0{padding-top:0 !important}.pr-md-0{padding-right:0 !important}.pb-md-0{padding-bottom:0 !important}.pl-md-0{padding-left:0 !important}.px-md-0{padding-right:0 !important;padding-left:0 !important}.py-md-0{padding-top:0 !important;padding-bottom:0 !important}.p-md-1{padding:.25rem !important}.pt-md-1{padding-top:.25rem !important}.pr-md-1{padding-right:.25rem !important}.pb-md-1{padding-bottom:.25rem !important}.pl-md-1{padding-left:.25rem !important}.px-md-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-md-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-md-2{padding:.5rem !important}.pt-md-2{padding-top:.5rem !important}.pr-md-2{padding-right:.5rem !important}.pb-md-2{padding-bottom:.5rem !important}.pl-md-2{padding-left:.5rem !important}.px-md-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-md-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-md-3{padding:.75rem !important}.pt-md-3{padding-top:.75rem !important}.pr-md-3{padding-right:.75rem !important}.pb-md-3{padding-bottom:.75rem !important}.pl-md-3{padding-left:.75rem !important}.px-md-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-md-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-md-4{padding:1rem !important}.pt-md-4{padding-top:1rem !important}.pr-md-4{padding-right:1rem !important}.pb-md-4{padding-bottom:1rem !important}.pl-md-4{padding-left:1rem !important}.px-md-4{padding-right:1rem !important;padding-left:1rem !important}.py-md-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-md-5{padding:1.5rem !important}.pt-md-5{padding-top:1.5rem !important}.pr-md-5{padding-right:1.5rem !important}.pb-md-5{padding-bottom:1.5rem !important}.pl-md-5{padding-left:1.5rem !important}.px-md-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-md-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-md-6{padding:2rem !important}.pt-md-6{padding-top:2rem !important}.pr-md-6{padding-right:2rem !important}.pb-md-6{padding-bottom:2rem !important}.pl-md-6{padding-left:2rem !important}.px-md-6{padding-right:2rem !important;padding-left:2rem !important}.py-md-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-md-7{padding:2.5rem !important}.pt-md-7{padding-top:2.5rem !important}.pr-md-7{padding-right:2.5rem !important}.pb-md-7{padding-bottom:2.5rem !important}.pl-md-7{padding-left:2.5rem !important}.px-md-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-md-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-md-8{padding:3rem !important}.pt-md-8{padding-top:3rem !important}.pr-md-8{padding-right:3rem !important}.pb-md-8{padding-bottom:3rem !important}.pl-md-8{padding-left:3rem !important}.px-md-8{padding-right:3rem !important;padding-left:3rem !important}.py-md-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-md-9{padding:3.5rem !important}.pt-md-9{padding-top:3.5rem !important}.pr-md-9{padding-right:3.5rem !important}.pb-md-9{padding-bottom:3.5rem !important}.pl-md-9{padding-left:3.5rem !important}.px-md-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-md-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-md-10{padding:4rem !important}.pt-md-10{padding-top:4rem !important}.pr-md-10{padding-right:4rem !important}.pb-md-10{padding-bottom:4rem !important}.pl-md-10{padding-left:4rem !important}.px-md-10{padding-right:4rem !important;padding-left:4rem !important}.py-md-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 66.5rem){.p-lg-0{padding:0 !important}.pt-lg-0{padding-top:0 !important}.pr-lg-0{padding-right:0 !important}.pb-lg-0{padding-bottom:0 !important}.pl-lg-0{padding-left:0 !important}.px-lg-0{padding-right:0 !important;padding-left:0 !important}.py-lg-0{padding-top:0 !important;padding-bottom:0 !important}.p-lg-1{padding:.25rem !important}.pt-lg-1{padding-top:.25rem !important}.pr-lg-1{padding-right:.25rem !important}.pb-lg-1{padding-bottom:.25rem !important}.pl-lg-1{padding-left:.25rem !important}.px-lg-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-lg-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-lg-2{padding:.5rem !important}.pt-lg-2{padding-top:.5rem !important}.pr-lg-2{padding-right:.5rem !important}.pb-lg-2{padding-bottom:.5rem !important}.pl-lg-2{padding-left:.5rem !important}.px-lg-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-lg-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-lg-3{padding:.75rem !important}.pt-lg-3{padding-top:.75rem !important}.pr-lg-3{padding-right:.75rem !important}.pb-lg-3{padding-bottom:.75rem !important}.pl-lg-3{padding-left:.75rem !important}.px-lg-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-lg-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-lg-4{padding:1rem !important}.pt-lg-4{padding-top:1rem !important}.pr-lg-4{padding-right:1rem !important}.pb-lg-4{padding-bottom:1rem !important}.pl-lg-4{padding-left:1rem !important}.px-lg-4{padding-right:1rem !important;padding-left:1rem !important}.py-lg-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-lg-5{padding:1.5rem !important}.pt-lg-5{padding-top:1.5rem !important}.pr-lg-5{padding-right:1.5rem !important}.pb-lg-5{padding-bottom:1.5rem !important}.pl-lg-5{padding-left:1.5rem !important}.px-lg-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-lg-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-lg-6{padding:2rem !important}.pt-lg-6{padding-top:2rem !important}.pr-lg-6{padding-right:2rem !important}.pb-lg-6{padding-bottom:2rem !important}.pl-lg-6{padding-left:2rem !important}.px-lg-6{padding-right:2rem !important;padding-left:2rem !important}.py-lg-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-lg-7{padding:2.5rem !important}.pt-lg-7{padding-top:2.5rem !important}.pr-lg-7{padding-right:2.5rem !important}.pb-lg-7{padding-bottom:2.5rem !important}.pl-lg-7{padding-left:2.5rem !important}.px-lg-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-lg-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-lg-8{padding:3rem !important}.pt-lg-8{padding-top:3rem !important}.pr-lg-8{padding-right:3rem !important}.pb-lg-8{padding-bottom:3rem !important}.pl-lg-8{padding-left:3rem !important}.px-lg-8{padding-right:3rem !important;padding-left:3rem !important}.py-lg-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-lg-9{padding:3.5rem !important}.pt-lg-9{padding-top:3.5rem !important}.pr-lg-9{padding-right:3.5rem !important}.pb-lg-9{padding-bottom:3.5rem !important}.pl-lg-9{padding-left:3.5rem !important}.px-lg-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-lg-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-lg-10{padding:4rem !important}.pt-lg-10{padding-top:4rem !important}.pr-lg-10{padding-right:4rem !important}.pb-lg-10{padding-bottom:4rem !important}.pl-lg-10{padding-left:4rem !important}.px-lg-10{padding-right:4rem !important;padding-left:4rem !important}.py-lg-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media (min-width: 87.5rem){.p-xl-0{padding:0 !important}.pt-xl-0{padding-top:0 !important}.pr-xl-0{padding-right:0 !important}.pb-xl-0{padding-bottom:0 !important}.pl-xl-0{padding-left:0 !important}.px-xl-0{padding-right:0 !important;padding-left:0 !important}.py-xl-0{padding-top:0 !important;padding-bottom:0 !important}.p-xl-1{padding:.25rem !important}.pt-xl-1{padding-top:.25rem !important}.pr-xl-1{padding-right:.25rem !important}.pb-xl-1{padding-bottom:.25rem !important}.pl-xl-1{padding-left:.25rem !important}.px-xl-1{padding-right:.25rem !important;padding-left:.25rem !important}.py-xl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-xl-2{padding:.5rem !important}.pt-xl-2{padding-top:.5rem !important}.pr-xl-2{padding-right:.5rem !important}.pb-xl-2{padding-bottom:.5rem !important}.pl-xl-2{padding-left:.5rem !important}.px-xl-2{padding-right:.5rem !important;padding-left:.5rem !important}.py-xl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-xl-3{padding:.75rem !important}.pt-xl-3{padding-top:.75rem !important}.pr-xl-3{padding-right:.75rem !important}.pb-xl-3{padding-bottom:.75rem !important}.pl-xl-3{padding-left:.75rem !important}.px-xl-3{padding-right:.75rem !important;padding-left:.75rem !important}.py-xl-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-xl-4{padding:1rem !important}.pt-xl-4{padding-top:1rem !important}.pr-xl-4{padding-right:1rem !important}.pb-xl-4{padding-bottom:1rem !important}.pl-xl-4{padding-left:1rem !important}.px-xl-4{padding-right:1rem !important;padding-left:1rem !important}.py-xl-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-xl-5{padding:1.5rem !important}.pt-xl-5{padding-top:1.5rem !important}.pr-xl-5{padding-right:1.5rem !important}.pb-xl-5{padding-bottom:1.5rem !important}.pl-xl-5{padding-left:1.5rem !important}.px-xl-5{padding-right:1.5rem !important;padding-left:1.5rem !important}.py-xl-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-xl-6{padding:2rem !important}.pt-xl-6{padding-top:2rem !important}.pr-xl-6{padding-right:2rem !important}.pb-xl-6{padding-bottom:2rem !important}.pl-xl-6{padding-left:2rem !important}.px-xl-6{padding-right:2rem !important;padding-left:2rem !important}.py-xl-6{padding-top:2rem !important;padding-bottom:2rem !important}.p-xl-7{padding:2.5rem !important}.pt-xl-7{padding-top:2.5rem !important}.pr-xl-7{padding-right:2.5rem !important}.pb-xl-7{padding-bottom:2.5rem !important}.pl-xl-7{padding-left:2.5rem !important}.px-xl-7{padding-right:2.5rem !important;padding-left:2.5rem !important}.py-xl-7{padding-top:2.5rem !important;padding-bottom:2.5rem !important}.p-xl-8{padding:3rem !important}.pt-xl-8{padding-top:3rem !important}.pr-xl-8{padding-right:3rem !important}.pb-xl-8{padding-bottom:3rem !important}.pl-xl-8{padding-left:3rem !important}.px-xl-8{padding-right:3rem !important;padding-left:3rem !important}.py-xl-8{padding-top:3rem !important;padding-bottom:3rem !important}.p-xl-9{padding:3.5rem !important}.pt-xl-9{padding-top:3.5rem !important}.pr-xl-9{padding-right:3.5rem !important}.pb-xl-9{padding-bottom:3.5rem !important}.pl-xl-9{padding-left:3.5rem !important}.px-xl-9{padding-right:3.5rem !important;padding-left:3.5rem !important}.py-xl-9{padding-top:3.5rem !important;padding-bottom:3.5rem !important}.p-xl-10{padding:4rem !important}.pt-xl-10{padding-top:4rem !important}.pr-xl-10{padding-right:4rem !important}.pb-xl-10{padding-bottom:4rem !important}.pl-xl-10{padding-left:4rem !important}.px-xl-10{padding-right:4rem !important;padding-left:4rem !important}.py-xl-10{padding-top:4rem !important;padding-bottom:4rem !important}}@media print{.site-footer,.site-button,#edit-this-page,#back-to-top,.site-nav,.main-header{display:none !important}.side-bar{width:100%;height:auto;border-right:0 !important}.site-header{border-bottom:1px solid #eeebee}.site-title{font-size:16px !important;font-weight:700 !important}.text-small{font-size:8pt !important}pre.highlight{border:1px solid #eeebee}.main{max-width:none;margin-left:0}}a.skip-to-main{left:-999px;position:absolute;top:auto;width:1px;height:1px;overflow:hidden;z-index:-999}a.skip-to-main:focus,a.skip-to-main:active{color:#7253ed;background-color:#fff;left:auto;top:auto;width:30%;height:auto;overflow:auto;margin:10px 35%;padding:5px;border-radius:15px;border:4px solid #5e41d0;text-align:center;font-size:1.2em;z-index:999}div.opaque{background-color:#fff} diff --git a/assets/images/just-the-docs.png b/assets/images/just-the-docs.png new file mode 100644 index 0000000000..81c33065f2 Binary files /dev/null and b/assets/images/just-the-docs.png differ diff --git a/assets/images/large-image.jpg b/assets/images/large-image.jpg new file mode 100644 index 0000000000..c007781c27 Binary files /dev/null and b/assets/images/large-image.jpg differ diff --git a/assets/images/search.svg b/assets/images/search.svg new file mode 100644 index 0000000000..421ca4df01 --- /dev/null +++ b/assets/images/search.svg @@ -0,0 +1 @@ +Search diff --git a/assets/images/small-image.jpg b/assets/images/small-image.jpg new file mode 100644 index 0000000000..5bf58a9493 Binary files /dev/null and b/assets/images/small-image.jpg differ diff --git a/assets/js/just-the-docs.js b/assets/js/just-the-docs.js new file mode 100644 index 0000000000..21c50817c7 --- /dev/null +++ b/assets/js/just-the-docs.js @@ -0,0 +1,497 @@ +(function (jtd, undefined) { + +// Event handling + +jtd.addEvent = function(el, type, handler) { + if (el.attachEvent) el.attachEvent('on'+type, handler); else el.addEventListener(type, handler); +} +jtd.removeEvent = function(el, type, handler) { + if (el.detachEvent) el.detachEvent('on'+type, handler); else el.removeEventListener(type, handler); +} +jtd.onReady = function(ready) { + // in case the document is already rendered + if (document.readyState!='loading') ready(); + // modern browsers + else if (document.addEventListener) document.addEventListener('DOMContentLoaded', ready); + // IE <= 8 + else document.attachEvent('onreadystatechange', function(){ + if (document.readyState=='complete') ready(); + }); +} + +// Show/hide mobile menu + +function initNav() { + jtd.addEvent(document, 'click', function(e){ + var target = e.target; + while (target && !(target.classList && target.classList.contains('nav-list-expander'))) { + target = target.parentNode; + } + if (target) { + e.preventDefault(); + target.parentNode.classList.toggle('active'); + } + }); + + const siteNav = document.getElementById('site-nav'); + const mainHeader = document.getElementById('main-header'); + const menuButton = document.getElementById('menu-button'); + + jtd.addEvent(menuButton, 'click', function(e){ + e.preventDefault(); + + if (menuButton.classList.toggle('nav-open')) { + siteNav.classList.add('nav-open'); + mainHeader.classList.add('nav-open'); + } else { + siteNav.classList.remove('nav-open'); + mainHeader.classList.remove('nav-open'); + } + }); +} +// Site search + +function initSearch() { + var request = new XMLHttpRequest(); + request.open('GET', '/ostree/assets/js/search-data.json', true); + + request.onload = function(){ + if (request.status >= 200 && request.status < 400) { + var docs = JSON.parse(request.responseText); + + lunr.tokenizer.separator = /[\s\-/]+/ + + var index = lunr(function(){ + this.ref('id'); + this.field('title', { boost: 200 }); + this.field('content', { boost: 2 }); + this.field('relUrl'); + this.metadataWhitelist = ['position'] + + for (var i in docs) { + + this.add({ + id: i, + title: docs[i].title, + content: docs[i].content, + relUrl: docs[i].relUrl + }); + } + }); + + searchLoaded(index, docs); + } else { + console.log('Error loading ajax request. Request status:' + request.status); + } + }; + + request.onerror = function(){ + console.log('There was a connection error'); + }; + + request.send(); +} + +function searchLoaded(index, docs) { + var index = index; + var docs = docs; + var searchInput = document.getElementById('search-input'); + var searchResults = document.getElementById('search-results'); + var mainHeader = document.getElementById('main-header'); + var currentInput; + var currentSearchIndex = 0; + + function showSearch() { + document.documentElement.classList.add('search-active'); + } + + function hideSearch() { + document.documentElement.classList.remove('search-active'); + } + + function update() { + currentSearchIndex++; + + var input = searchInput.value; + if (input === '') { + hideSearch(); + } else { + showSearch(); + // scroll search input into view, workaround for iOS Safari + window.scroll(0, -1); + setTimeout(function(){ window.scroll(0, 0); }, 0); + } + if (input === currentInput) { + return; + } + currentInput = input; + searchResults.innerHTML = ''; + if (input === '') { + return; + } + + var results = index.query(function (query) { + var tokens = lunr.tokenizer(input) + query.term(tokens, { + boost: 10 + }); + query.term(tokens, { + wildcard: lunr.Query.wildcard.TRAILING + }); + }); + + if ((results.length == 0) && (input.length > 2)) { + var tokens = lunr.tokenizer(input).filter(function(token, i) { + return token.str.length < 20; + }) + if (tokens.length > 0) { + results = index.query(function (query) { + query.term(tokens, { + editDistance: Math.round(Math.sqrt(input.length / 2 - 1)) + }); + }); + } + } + + if (results.length == 0) { + var noResultsDiv = document.createElement('div'); + noResultsDiv.classList.add('search-no-result'); + noResultsDiv.innerText = 'No results found'; + searchResults.appendChild(noResultsDiv); + + } else { + var resultsList = document.createElement('ul'); + resultsList.classList.add('search-results-list'); + searchResults.appendChild(resultsList); + + addResults(resultsList, results, 0, 10, 100, currentSearchIndex); + } + + function addResults(resultsList, results, start, batchSize, batchMillis, searchIndex) { + if (searchIndex != currentSearchIndex) { + return; + } + for (var i = start; i < (start + batchSize); i++) { + if (i == results.length) { + return; + } + addResult(resultsList, results[i]); + } + setTimeout(function() { + addResults(resultsList, results, start + batchSize, batchSize, batchMillis, searchIndex); + }, batchMillis); + } + + function addResult(resultsList, result) { + var doc = docs[result.ref]; + + var resultsListItem = document.createElement('li'); + resultsListItem.classList.add('search-results-list-item'); + resultsList.appendChild(resultsListItem); + + var resultLink = document.createElement('a'); + resultLink.classList.add('search-result'); + resultLink.setAttribute('href', doc.url); + resultsListItem.appendChild(resultLink); + + var resultTitle = document.createElement('div'); + resultTitle.classList.add('search-result-title'); + resultLink.appendChild(resultTitle); + + // note: the SVG svg-doc is only loaded as a Jekyll include if site.search_enabled is true; see _includes/icons/icons.html + var resultDoc = document.createElement('div'); + resultDoc.classList.add('search-result-doc'); + resultDoc.innerHTML = ''; + resultTitle.appendChild(resultDoc); + + var resultDocTitle = document.createElement('div'); + resultDocTitle.classList.add('search-result-doc-title'); + resultDocTitle.innerHTML = doc.doc; + resultDoc.appendChild(resultDocTitle); + var resultDocOrSection = resultDocTitle; + + if (doc.doc != doc.title) { + resultDoc.classList.add('search-result-doc-parent'); + var resultSection = document.createElement('div'); + resultSection.classList.add('search-result-section'); + resultSection.innerHTML = doc.title; + resultTitle.appendChild(resultSection); + resultDocOrSection = resultSection; + } + + var metadata = result.matchData.metadata; + var titlePositions = []; + var contentPositions = []; + for (var j in metadata) { + var meta = metadata[j]; + if (meta.title) { + var positions = meta.title.position; + for (var k in positions) { + titlePositions.push(positions[k]); + } + } + if (meta.content) { + var positions = meta.content.position; + for (var k in positions) { + var position = positions[k]; + var previewStart = position[0]; + var previewEnd = position[0] + position[1]; + var ellipsesBefore = true; + var ellipsesAfter = true; + for (var k = 0; k < 5; k++) { + var nextSpace = doc.content.lastIndexOf(' ', previewStart - 2); + var nextDot = doc.content.lastIndexOf('. ', previewStart - 2); + if ((nextDot >= 0) && (nextDot > nextSpace)) { + previewStart = nextDot + 1; + ellipsesBefore = false; + break; + } + if (nextSpace < 0) { + previewStart = 0; + ellipsesBefore = false; + break; + } + previewStart = nextSpace + 1; + } + for (var k = 0; k < 10; k++) { + var nextSpace = doc.content.indexOf(' ', previewEnd + 1); + var nextDot = doc.content.indexOf('. ', previewEnd + 1); + if ((nextDot >= 0) && (nextDot < nextSpace)) { + previewEnd = nextDot; + ellipsesAfter = false; + break; + } + if (nextSpace < 0) { + previewEnd = doc.content.length; + ellipsesAfter = false; + break; + } + previewEnd = nextSpace; + } + contentPositions.push({ + highlight: position, + previewStart: previewStart, previewEnd: previewEnd, + ellipsesBefore: ellipsesBefore, ellipsesAfter: ellipsesAfter + }); + } + } + } + + if (titlePositions.length > 0) { + titlePositions.sort(function(p1, p2){ return p1[0] - p2[0] }); + resultDocOrSection.innerHTML = ''; + addHighlightedText(resultDocOrSection, doc.title, 0, doc.title.length, titlePositions); + } + + if (contentPositions.length > 0) { + contentPositions.sort(function(p1, p2){ return p1.highlight[0] - p2.highlight[0] }); + var contentPosition = contentPositions[0]; + var previewPosition = { + highlight: [contentPosition.highlight], + previewStart: contentPosition.previewStart, previewEnd: contentPosition.previewEnd, + ellipsesBefore: contentPosition.ellipsesBefore, ellipsesAfter: contentPosition.ellipsesAfter + }; + var previewPositions = [previewPosition]; + for (var j = 1; j < contentPositions.length; j++) { + contentPosition = contentPositions[j]; + if (previewPosition.previewEnd < contentPosition.previewStart) { + previewPosition = { + highlight: [contentPosition.highlight], + previewStart: contentPosition.previewStart, previewEnd: contentPosition.previewEnd, + ellipsesBefore: contentPosition.ellipsesBefore, ellipsesAfter: contentPosition.ellipsesAfter + } + previewPositions.push(previewPosition); + } else { + previewPosition.highlight.push(contentPosition.highlight); + previewPosition.previewEnd = contentPosition.previewEnd; + previewPosition.ellipsesAfter = contentPosition.ellipsesAfter; + } + } + + var resultPreviews = document.createElement('div'); + resultPreviews.classList.add('search-result-previews'); + resultLink.appendChild(resultPreviews); + + var content = doc.content; + for (var j = 0; j < Math.min(previewPositions.length, 3); j++) { + var position = previewPositions[j]; + + var resultPreview = document.createElement('div'); + resultPreview.classList.add('search-result-preview'); + resultPreviews.appendChild(resultPreview); + + if (position.ellipsesBefore) { + resultPreview.appendChild(document.createTextNode('... ')); + } + addHighlightedText(resultPreview, content, position.previewStart, position.previewEnd, position.highlight); + if (position.ellipsesAfter) { + resultPreview.appendChild(document.createTextNode(' ...')); + } + } + } + var resultRelUrl = document.createElement('span'); + resultRelUrl.classList.add('search-result-rel-url'); + resultRelUrl.innerText = doc.relUrl; + resultTitle.appendChild(resultRelUrl); + } + + function addHighlightedText(parent, text, start, end, positions) { + var index = start; + for (var i in positions) { + var position = positions[i]; + var span = document.createElement('span'); + span.innerHTML = text.substring(index, position[0]); + parent.appendChild(span); + index = position[0] + position[1]; + var highlight = document.createElement('span'); + highlight.classList.add('search-result-highlight'); + highlight.innerHTML = text.substring(position[0], index); + parent.appendChild(highlight); + } + var span = document.createElement('span'); + span.innerHTML = text.substring(index, end); + parent.appendChild(span); + } + } + + jtd.addEvent(searchInput, 'focus', function(){ + setTimeout(update, 0); + }); + + jtd.addEvent(searchInput, 'keyup', function(e){ + switch (e.keyCode) { + case 27: // When esc key is pressed, hide the results and clear the field + searchInput.value = ''; + break; + case 38: // arrow up + case 40: // arrow down + case 13: // enter + e.preventDefault(); + return; + } + update(); + }); + + jtd.addEvent(searchInput, 'keydown', function(e){ + switch (e.keyCode) { + case 38: // arrow up + e.preventDefault(); + var active = document.querySelector('.search-result.active'); + if (active) { + active.classList.remove('active'); + if (active.parentElement.previousSibling) { + var previous = active.parentElement.previousSibling.querySelector('.search-result'); + previous.classList.add('active'); + } + } + return; + case 40: // arrow down + e.preventDefault(); + var active = document.querySelector('.search-result.active'); + if (active) { + if (active.parentElement.nextSibling) { + var next = active.parentElement.nextSibling.querySelector('.search-result'); + active.classList.remove('active'); + next.classList.add('active'); + } + } else { + var next = document.querySelector('.search-result'); + if (next) { + next.classList.add('active'); + } + } + return; + case 13: // enter + e.preventDefault(); + var active = document.querySelector('.search-result.active'); + if (active) { + active.click(); + } else { + var first = document.querySelector('.search-result'); + if (first) { + first.click(); + } + } + return; + } + }); + + jtd.addEvent(document, 'click', function(e){ + if (e.target != searchInput) { + hideSearch(); + } + }); +} + +// Switch theme + +jtd.getTheme = function() { + var cssFileHref = document.querySelector('[rel="stylesheet"]').getAttribute('href'); + return cssFileHref.substring(cssFileHref.lastIndexOf('-') + 1, cssFileHref.length - 4); +} + +jtd.setTheme = function(theme) { + var cssFile = document.querySelector('[rel="stylesheet"]'); + cssFile.setAttribute('href', '/ostree/assets/css/just-the-docs-' + theme + '.css'); +} + +// Scroll site-nav to ensure the link to the current page is visible + +function scrollNav() { + const href = document.location.pathname; + const siteNav = document.getElementById('site-nav'); + const targetLink = siteNav.querySelector('a[href="' + href + '"], a[href="' + href + '/"]'); + if(targetLink){ + const rect = targetLink.getBoundingClientRect(); + siteNav.scrollBy(0, rect.top - 3*rect.height); + } +} + +// Document ready + +jtd.onReady(function(){ + initNav(); + initSearch(); + scrollNav(); +}); + +// Copy button on code + +jtd.onReady(function(){ + + var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock > div.content, figure.highlight'); + + // note: the SVG svg-copied and svg-copy is only loaded as a Jekyll include if site.enable_copy_code_button is true; see _includes/icons/icons.html + var svgCopied = ''; + var svgCopy = ''; + + codeBlocks.forEach(codeBlock => { + var copyButton = document.createElement('button'); + var timeout = null; + copyButton.type = 'button'; + copyButton.ariaLabel = 'Copy code to clipboard'; + copyButton.innerHTML = svgCopy; + codeBlock.append(copyButton); + + copyButton.addEventListener('click', function () { + if(timeout === null) { + var code = (codeBlock.querySelector('pre:not(.lineno, .highlight)') || codeBlock.querySelector('code')).innerText; + window.navigator.clipboard.writeText(code); + + copyButton.innerHTML = svgCopied; + + var timeoutSetting = 4000; + + timeout = setTimeout(function () { + copyButton.innerHTML = svgCopy; + timeout = null; + }, timeoutSetting); + } + }); + }); + +}); + +})(window.jtd = window.jtd || {}); + + diff --git a/assets/js/search-data.json b/assets/js/search-data.json new file mode 100644 index 0000000000..ffb06b324f --- /dev/null +++ b/assets/js/search-data.json @@ -0,0 +1,989 @@ +{"0": { + "doc": "Contributing", + "title": "Contributing", + "content": ". | Submitting patches | Commit message style | Running the test suite | Coding style | Contributing Tutorial | Release process | . ", + "url": "/ostree/CONTRIBUTING/", + + "relUrl": "/CONTRIBUTING/" + },"1": { + "doc": "Contributing", + "title": "Submitting patches", + "content": "A majority of current maintainers prefer the GitHub pull request model, and this motivated moving the primary git repository to https://github.com/ostreedev/ostree. However, we do not use the “Merge pull request” button, because we do not like merge commits for one-patch pull requests, among other reasons. See this issue for more information. Instead, we use an instance of Homu, currently known as cgwalters-bot. As a review proceeds, the preferred method is to push fixup! commits. Any commits committed with the --fixup option will have have the word fixup! in its commit title. This is to indicate that this particular commit will be squashed with the commit that was specified in this command, git commit --fixup <commit ref or hash>. Homu knows how to use --autosquash when performing the final merge. See the Git documentation for more information. Alternative methods if you don’t like GitHub (also fully supported): . | Send mail to ostree-list@gnome.org, with the patch attached | Attach them to https://bugzilla.gnome.org/ | . It is likely however once a patch is ready to apply a maintainer will push it to a GitHub PR, and merge via Homu. ", + "url": "/ostree/CONTRIBUTING/#submitting-patches", + + "relUrl": "/CONTRIBUTING/#submitting-patches" + },"2": { + "doc": "Contributing", + "title": "Commit message style", + "content": "Please look at git log and match the commit log style, which is very similar to the Linux kernel. You may use Signed-off-by, but we’re not requiring it. General Commit Message Guidelines: . | Title . | Specify the context or category of the changes e.g. lib for library changes, docs for document changes, bin/<command-name> for command changes, etc. | Begin the title with the first letter of the first word capitalized. | Aim for less than 50 characters, otherwise 72 characters max. | Do not end the title with a period. | Use an imperative tone. | . | Body . | Separate the body with a blank line after the title. | Begin a paragraph with the first letter of the first word capitalized. | Each paragraph should be formatted within 72 characters. | Content should be about what was changed and why this change was made. | If your commit fixes an issue, the commit message should end with Closes: #<number>. | . | . Commit Message example: . <context>: Less than 50 characters for subject title A paragraph of the body should be within 72 characters. This paragraph is also less than 72 characters. For more information see How to Write a Git Commit Message . Editing a Committed Message: . To edit the message from the most recent commit run git commit --amend. To change older commits on the branch use git rebase -i. For a successful rebase have the branch track upstream main. Once the changes have been made and saved, run git push --force origin <branch-name>. ", + "url": "/ostree/CONTRIBUTING/#commit-message-style", + + "relUrl": "/CONTRIBUTING/#commit-message-style" + },"3": { + "doc": "Contributing", + "title": "Running the test suite", + "content": "OSTree uses both make check and supports the Installed Tests model as well (if --enable-installed-tests is provided). ", + "url": "/ostree/CONTRIBUTING/#running-the-test-suite", + + "relUrl": "/CONTRIBUTING/#running-the-test-suite" + },"4": { + "doc": "Contributing", + "title": "Coding style", + "content": "Indentation is GNU. Files should start with the appropriate mode lines. Use GCC __attribute__((cleanup)) wherever possible. If interacting with a third party library, try defining local cleanup macros. Use GError and GCancellable where appropriate. Prefer returning gboolean to signal success/failure, and have output values as parameters. Prefer linear control flow inside functions (aside from standard loops). In other words, avoid “early exits” or use of goto besides goto out;. This is an example of an “early exit”: . static gboolean myfunc (...) { gboolean ret = FALSE; /* some code */ /* some more code */ if (condition) return FALSE; /* some more code */ ret = TRUE; out: return ret; } . If you must shortcut, use: . if (condition) { ret = TRUE; goto out; } . A consequence of this restriction is that you are encouraged to avoid deep nesting of loops or conditionals. Create internal static helper functions, particularly inside loops. For example, rather than: . while (condition) { /* some code */ if (condition) { for (i = 0; i < somevalue; i++) { if (condition) { /* deeply nested code */ } /* more nested code */ } } } . Instead do this: . static gboolean helperfunc (..., GError **error) { if (condition) { /* deeply nested code */ } /* more nested code */ return ret; } while (condition) { /* some code */ if (!condition) continue; for (i = 0; i < somevalue; i++) { if (!helperfunc (..., i, error)) goto out; } } . ", + "url": "/ostree/CONTRIBUTING/#coding-style", + + "relUrl": "/CONTRIBUTING/#coding-style" + },"5": { + "doc": "Contributing", + "title": "Contributing Tutorial", + "content": "For a detailed walk-through on building, modifying, and testing, see this tutorial on how to start contributing to OSTree. ", + "url": "/ostree/CONTRIBUTING/#contributing-tutorial", + + "relUrl": "/CONTRIBUTING/#contributing-tutorial" + },"6": { + "doc": "Contributing", + "title": "Release process", + "content": "Releases can be performed by creating a new release ticket and following the steps in the checklist there. ", + "url": "/ostree/CONTRIBUTING/#release-process", + + "relUrl": "/CONTRIBUTING/#release-process" + },"7": { + "doc": "Historical OSTree README", + "title": "Historical OSTree README", + "content": "This file is outdated, but some of the text here is still useful for historical context. I’m preserving it (explicitly still in the tree) for posterity. ", + "url": "/ostree/README-historical/", + + "relUrl": "/README-historical/" + },"8": { + "doc": "Historical OSTree README", + "title": "Problem statement", + "content": "Hacking on the core operating system is painful - this includes most of GNOME from upower and NetworkManager up to gnome-shell. I want a system that matches these requirements: . | Does not disturb your existing OS | Is not terribly slow to use | Shares your $HOME - you have your data | Allows easy rollback | Ideally allows access to existing apps | . ", + "url": "/ostree/README-historical/#problem-statement", + + "relUrl": "/README-historical/#problem-statement" + },"9": { + "doc": "Historical OSTree README", + "title": "Comparison with existing tools", + "content": ". | Virtualization . Fails on points 2) and 3). Actually qemu-kvm can be pretty fast, but in a lot of cases there is no substitute for actually booting on bare metal; GNOME 3 really needs some hardware GPU acceleration. | Rebuilding distribution packages . Fails on points 1) and 4). Is also just very annoying: dpkg/rpm both want tarballs, which you don’t have since you’re working from git. The suggested “mock/pbuilder” type chroot builds are slow. And even with non-chroot builds there is lots of pointless build wrapping going on. Both dpkg and rpm also are poor at helping you revert back to the original system. All of this can be scripted to be less bad of course - and I have worked on such scripts. But fundamentally you’re still fighting the system, and if you’re hacking on a lowlevel library like say glib, you can easily get yourself to the point where you need a recovery CD - at that point your edit/compile/debug cycle is just too long. | “sudo make install” . Now your system is in an undefined state. You can use e.g. rpm -qV to try to find out what you overwrote, but neither dpkg nor rpm will help clean up any files left over that aren’t shipped by the old package. This is most realistic option for people hacking on system components currently, but ostree will be better. | LXC / containers . Fails on 3), and 4) is questionable. Also shares the annoying part of rebuilding distribution packages. LXC is focused on running multiple server systems at the same time, which isn’t what we want (at least, not right now), and honestly even trying to support that for a graphical desktop would be a lot of tricky work, for example getting two GDM instances not to fight over VT allocations. But some bits of the technology may make sense to use. | jhbuild + distribution packages . The state of the art in GNOME - but can only build non-root things - this means you can’t build NetworkManager, and thus are permanently stuck on whatever the distro provides. | . ", + "url": "/ostree/README-historical/#comparison-with-existing-tools", + + "relUrl": "/README-historical/#comparison-with-existing-tools" + },"10": { + "doc": "Historical OSTree README", + "title": "Who is ostree for?", + "content": "First - operating system developers and testers. I specifically keep a few people in mind - Dan Williams and Eric Anholt, as well as myself obviously. For Eric Anholt, a key use case for him is being able to try out the latest gnome-shell, and combine it with his work on Mesa, and see how it works/performs - while retaining the ability to roll back if one or both breaks. The rollback concept is absolutely key for shipping anything to enthusiasts or knowledable testers. With a system like this, a tester can easily perform a local rollback - something just not well supported by dpkg/rpm. (What about Conary? See below.) . Also, distributing operating system trees (instead of packages) gives us a sane place to perform automated QA before we ship it to testers. We should never be wasting these people’s time. Even better, this system would allow testers to bisect across operating system builds, and do so very efficiently. ", + "url": "/ostree/README-historical/#who-is-ostree-for", + + "relUrl": "/README-historical/#who-is-ostree-for" + },"11": { + "doc": "Historical OSTree README", + "title": "The core idea - chroots", + "content": "chroots are the original lightweight “virtualization”. Let’s use them. So basically, you install a mainstream distribution (say Debian). It has a root filesystem like this: . /usr /etc /home ... Now, what we can do is have a system that installs chroots as a subdirectory of the root, like: . /ostree/gnomeos-3.0-opt-393a4555/{usr,etc,sbin,...} /ostree/gnomeos-3.2-opt-7e9788a2/{usr,etc,sbin,...} . These live in the same root filesystem as your regular distribution (Note though, the root partition should be reasonably sized, or hopefully you’ve used just one big partition). You should be able to boot into one of these roots. Since ostree lives inside a distro created partition, a tricky part here is that we need to know how to interact with the installed distribution’s grub. This is an annoying but tractable problem. First, we install a kernel+initramfs alongside the distribution’s. Then, we have a “trampoline” ostree-init binary which is statically linked, and boot the kernel with init=/ostree/ostree-init. This then takes care of chrooting and running the init binary. An important note here is that we bind mount the real /home. This means you have your data. This also implies we share uid/gid, so /etc/passwd will have to be in sync. Probably what we’ll do is have a script to pull the data from the “host” OS. I’ve decided for now to move /var into /ostree to avoid sharing it with the “host” distribution, because in practice we’re likely to hit incompatibilities. Do note however /etc lives inside the OSTree; it’s presently versioned and readonly like everything else. On a pure OSTree system, the filesystem layout will look like this: . |-- boot |-- home |-- ostree |-- var |-- current -> gnomeos-3.2-opt-7e9788a2 |-- gnomeos-3.0-opt-393a4555 | |-- etc | |-- lib | |-- mnt | |-- proc | |-- run | |-- sbin | |-- srv | |-- sys | `-- usr | `-- gnomeos-3.2-opt-7e9788a2 |-- etc |-- lib |-- mnt |-- proc |-- run |-- sbin |-- srv |-- sys | `-- usr |-- root . ", + "url": "/ostree/README-historical/#the-core-idea---chroots", + + "relUrl": "/README-historical/#the-core-idea---chroots" + },"12": { + "doc": "Historical OSTree README", + "title": "Making this efficient", + "content": "One of the first things you’ll probably ask is “but won’t that use a lot of disk space”? Indeed, it will, if you just unpack a set of RPMs or .debs into each root. Besides chroots, there’s another old Unix idea we can take advantage of - hard links. These allow sharing the underlying data of a file, with the tradeoff that changing any one file will change all names that point to it. This mutability means that we have to either: . | Make sure everything touching the operating system breaks hard links This is probably tractable over a long period of time, but if anything has a bug, then it corrupts the file effectively. | Make the core OS read-only, with a well-defined mechanism for mutating under the control of ostree. | . I chose 2. ", + "url": "/ostree/README-historical/#making-this-efficient", + + "relUrl": "/README-historical/#making-this-efficient" + },"13": { + "doc": "Historical OSTree README", + "title": "A userspace content-addressed versioning filesystem", + "content": "At its very core, that’s what ostree is. Just like git. If you understand git, you know it’s not like other revision control systems. git is effectively a specialized, userspace filesystem, and that is a very powerful idea. At the core of git is the idea of “content-addressed objects”. For background on this, see http://book.git-scm.com/7_how_git_stores_objects.html . Why not just use git? Basically because git is designed mainly for source trees - it goes to effort to be sure it’s compressing text for example, under the assumption that you have a lot of text. Its handling of binaries is very generic and unoptimized. In contrast, ostree is explicitly designed for binaries, and in particular one type of binary - ELF executables (or it will be once we start using bsdiff). Another big difference versus git is that ostree uses hard links between “checkouts” and the repository. This means each checkout uses almost no additional space, and is extremely fast to check out. We can do this because again each checkout is designed to be read-only. So we mentioned above there are: . /ostree/gnomeos-3.2-opt-7e9788a2 /ostree/gnomeos-3.2-opt-393a4555 . There is also a “repository” that looks like this: . /ostree/repo/objects/17/a95e8ca0ba655b09cb68d7288342588e867ee0.file /ostree/repo/objects/17/68625e7ff5a8db77904c77489dc6f07d4afdba.meta /ostree/repo/objects/17/cc01589dd8540d85c0f93f52b708500dbaa5a9.file /ostree/repo/objects/30 /ostree/repo/objects/30/6359b3ca7684358a3988afd005013f13c0c533.meta /ostree/repo/objects/30/8f3c03010cedd930b1db756ce659c064f0cd7f.meta /ostree/repo/objects/30/8cf0fd8e63dfff6a5f00ba5a48f3b92fb52de7.file /ostree/repo/objects/30/6cad7f027d69a46bb376044434bbf28d63e88d.file . Each object is either metadata (like a commit or tree), or a hard link to a regular file. Note that also unlike git, the checksum here includes metadata such as uid, gid, permissions, and extended attributes. (It does not include file access times, since those shouldn’t matter for the OS) . This is another important component to allowing the hardlinks. We wouldn’t want say all empty files to be shared necessarily. (Though maybe this is wrong, and since the OS is readonly, we can make all files owned by root without loss of generality). However this tradeoff means that we probably need a second index by content, so we don’t have to redownload the entire OS if permissions change =) . ", + "url": "/ostree/README-historical/#a-userspace-content-addressed-versioning-filesystem", + + "relUrl": "/README-historical/#a-userspace-content-addressed-versioning-filesystem" + },"14": { + "doc": "Historical OSTree README", + "title": "Atomic upgrades, rollback", + "content": "OSTree is designed to atomically swap operating systems - such that during an upgrade and reboot process, you either get the full new system, or the old one. There is no “Please don’t turn off your computer”. We do this by simply using a symbolic link like: . /ostree/current -> /ostree/gnomeos-3.4-opt-e3b0c4429 . Where gnomeos-e3b0c4429 has the full regular filesystem tree with usr/ etc/ directories as above. To upgrade or rollback (there is no difference internally), we simply check out a new tree into gnomeos-b90ae4763 for example, then swap the “current” symbolic link, then remove the old tree. But does this mean you have to reboot for OS upgrades? Very likely, yes - and this is no different from RPM/deb or whatever. They just typically lie to you about it =) . A typical model with RPM/deb is to unpack the new files, then use some IPC mechanism (SIGHUP, a control binary like /usr/sbin/apachectl) to signal the running process to reload. There are multiple problems with this - one is that in the new state, daemon A may depend on the updated configuration in daemon B. This may not be particularly common in default configurations, but it’s highly likely that that some deployments will have e.g. apache talking to a local MySQL instance. So you really want to do is only apply the updated configuration when all the files are in place; not after each RPM or .deb is installed. What’s even harder is the massive set of race conditions that are possible while RPM/deb are in the process of upgrading. Cron jobs are very likely to hit this. If we want the ability to apply updates to a live system, we could first pause execution of non-upgrade userspace tasks. This could be done via SIGSTOP for example. Then, we can swap around the filesystem tree, and then finally attempt to apply updates via SIGHUP, and if possible, restart processes. ", + "url": "/ostree/README-historical/#atomic-upgrades-rollback", + + "relUrl": "/README-historical/#atomic-upgrades-rollback" + },"15": { + "doc": "Historical OSTree README", + "title": "Configuration Management", + "content": "By now if you’ve thought about this problem domain before, you’re wondering about configuration management. In other words, if the OS is read only, how do I edit /etc/sudoers? . Well, have you ever been a system administrator on a zypper/yum system, done an RPM update, which then drops .rpmnew files in your /etc/ that you have to go and hunt for with “find” or something, and said to yourself, “Wow, this system is awesome!!!” ? Right, that’s what I thought. Configuration (and systems) management is a tricky problem, and I certainly don’t have a magic bullet. However, one large conceptual improvement I think is defaulting to “rebase” versus “merge”. This means that we won’t permit direct modification of /etc - instead, you HAVE to write a script which accomplishes your goals. To generate a tree, we check out a new copy, then run your script on top. If the script fails, we can roll back the update, or drop to a shell if interactive. However, we also need to consider cases where the administrator modifies state indirectly by a program. Think “adduser” for example. Possible approaches: . | Patch all of these programs to know how to write to the writable location, instead of the R/O bind mount overlay. | Move the data to /var | . ", + "url": "/ostree/README-historical/#configuration-management", + + "relUrl": "/README-historical/#configuration-management" + },"16": { + "doc": "Historical OSTree README", + "title": "What about “packages”?", + "content": "There are several complex and separate issues hiding in this seemingly simple question. I think OSTree always makes sense to use as a core operating system builder and updater. By “core” here I mean the parts that aren’t removable. Debian has Essential: yes, any other distribution has this too implicitly in the set of dependencies for their updater tool. Now, let me just say I will absolutely support using something like apt/yum/zypper (and consequently deb/rpm) on top of OSTree. This isn’t trivial, but there aren’t any conceptual issues. Concretely for example, RPM or .deb might make sense as a delivery vehicle for third party OS extensions. A canoncial example is the NVidia graphics driver. If one is using OSTree to build an operating system, then there has to be some API for applications. And that demands its own targeted solution - something like an evolved glick (zeroinstall is also similar). Current package systems are totally broken for application deployment though; for example, they will remove files away from under running applications on update. And we clearly need the ability to install and upgrade applications without rebooting the OS. ", + "url": "/ostree/README-historical/#what-about-packages", + + "relUrl": "/README-historical/#what-about-packages" + },"17": { + "doc": "Historical OSTree README", + "title": "Details of RPM installation", + "content": "We should be able to install LSB rpms. This implies providing “rpm”. The tricky part here is since the OS itself is not assembled via RPMs, we need to fake up a database of “provides” as if we were. Even harder would be maintaining binary compatibilty with any arbitrary %post scripts that may be run. ", + "url": "/ostree/README-historical/#details-of-rpm-installation", + + "relUrl": "/README-historical/#details-of-rpm-installation" + },"18": { + "doc": "Historical OSTree README", + "title": "What about BTRFS? Doesn’t it solve everything?", + "content": "In short, BTRFS is not a magic bullet, but yes - it helps significantly. The obvious thing to do is layer BTRFS under dpkg/rpm, and have a separate subvolume for /home so rollbacks don’t lose your data. See e.g. http://fedoraproject.org/wiki/Features/SystemRollbackWithBtrfs . As a general rule an issue with the BTRFS is that it can’t roll back just changes to things installed by RPM (i.e. what’s in rpm -qal). For example, it’s possible to e.g. run yum update, then edit something in /etc, reboot and notice things are broken, then roll back and have silently lost your changes to /etc. Another example is adding a new binary in /usr/local. You could say, “OK, we’ll use subvolumes for those!”. But then what about /var (and your VM images that live in /var/lib/libvirt ?) . Finally, probably the biggest disadvantage of the rpm/dpkg + BTRFS approach is it doesn’t solve the race conditions that happen when unpacking packages into the live system. This problem is really important to me. Note though ostree can definitely take advantage of BTRFS features! In particular, we could use “reflink” http://lwn.net/Articles/331808/ instead of hard links, and avoid having the object store corrupted if somehow the files are modified directly. ", + "url": "/ostree/README-historical/#what-about-btrfs--doesnt-it-solve-everything", + + "relUrl": "/README-historical/#what-about-btrfs--doesnt-it-solve-everything" + },"19": { + "doc": "Historical OSTree README", + "title": "Other systems", + "content": "I’ve spent a long time thinking about this problem, and here are some of the other possible solutions out there I looked at, and why I didn’t use them: . | Git: http://git-scm.com/ . Really awesome, and the core inspiration here. But like I mentioned above, not at all designed for binaries - we can make different tradeoffs. | bup: https://github.com/apenwarr/bup . bup is cool. But it shares the negative tradeoffs with git, though it does add positives of its own. It also inspired me. | git-annex: http://git-annex.branchable.com/git-annex/ . Looks interesting; I think this will share the same negative tradeoffs with git as far as using it for an OS goes. | schroot: http://www.debian-administration.org/articles/566 . Like LXC/containers, but just using a chroot. | NixOS: http://nixos.org/ . The NixOS people have a lot of really good ideas, and they’ve definitely thought about the problem space. However, their approach of checksumming all inputs to a package is pretty wacky. I don’t see the point, and moreover it uses gobs of disk space. | Conary: http://wiki.rpath.com/wiki/Conary:Updates_and_Rollbacks . If rpm/dpkg are like CVS, Conary is closer to Subversion. It’s not bad, but ostree is better than it for the exact same reasons git is better than Subversion. | BTRFS: http://en.wikipedia.org/wiki/Btrfs . See above. | Solaris IPS: http://hub.opensolaris.org/bin/view/Project+pkg/ . Rollback is ZFS level, so I think this shares the same tradeoffs as BTRFS+RPM/deb. They probably have some vertical integration though which definitely helps. Obviously we can’t use ZFS. | Jhbuild: https://live.gnome.org/Jhbuild . What we’ve been using in GNOME, and has the essential property of allowing you to “fall back” to a stable system. But ostree will blow it out of the water. | . ", + "url": "/ostree/README-historical/#other-systems", + + "relUrl": "/README-historical/#other-systems" + },"20": { + "doc": "Historical OSTree README", + "title": "Development", + "content": ". | OSTree wiki page: https://live.gnome.org/OSTree . | ostbuild wiki page: https://live.gnome.org/OSTree/Ostbuild . | Git repository: http://git.gnome.org/browse/ostree/ . | Deploying OSTree in the Gnome servers: https://bugzilla.gnome.org/show_bug.cgi?id=669772 . | . ", + "url": "/ostree/README-historical/#development", + + "relUrl": "/README-historical/#development" + },"21": { + "doc": "Adapting existing mainstream distributions", + "title": "Adapting existing mainstream distributions", + "content": ". | System layout | Booting and initramfs technology | System users and groups . | Static users and groups | sysusers.d | . | Adapting existing package managers | . ", + "url": "/ostree/adapting-existing/", + + "relUrl": "/adapting-existing/" + },"22": { + "doc": "Adapting existing mainstream distributions", + "title": "System layout", + "content": "First, OSTree encourages systems to implement UsrMove This is simply to avoid the need for more bind mounts. By default OSTree’s dracut hook creates a read-only bind mount over /usr; you can of course generate individual bind-mounts for /bin, all the /lib variants, etc. So it is not intended to be a hard requirement. Remember, because by default the system is booted into a chroot equivalent, there has to be some way to refer to the actual physical root filesystem. Therefore, your operating system tree should contain an empty /sysroot directory; at boot time, OSTree will make this a bind mount to the physical / root directory. There is precedent for this name in the initramfs context. You should furthermore make a toplevel symbolic link /ostree which points to /sysroot/ostree, so that the OSTree tool at runtime can consistently find the system data regardless of whether it’s operating on a physical root or inside a deployment. Because OSTree only preserves /var across upgrades (each deployment’s chroot directory will be garbage collected eventually), you will need to choose how to handle other toplevel writable directories specified by the Filesystem Hierarchy Standard. Your operating system may of course choose not to support some of these such as /usr/local, but following is the recommended set: . | /home → /var/home | /opt → /var/opt | /srv → /var/srv | /root → /var/roothome | /usr/local → /var/usrlocal | /mnt → /var/mnt | /tmp → /sysroot/tmp | . Furthermore, since /var is empty by default, your operating system will need to dynamically create the targets of these at boot. A good way to do this is using systemd-tmpfiles, if your OS uses systemd. For example: . d /var/log/journal 0755 root root - L /var/home - - - - ../sysroot/home d /var/opt 0755 root root - d /var/srv 0755 root root - d /var/roothome 0700 root root - d /var/usrlocal 0755 root root - d /var/usrlocal/bin 0755 root root - d /var/usrlocal/etc 0755 root root - d /var/usrlocal/games 0755 root root - d /var/usrlocal/include 0755 root root - d /var/usrlocal/lib 0755 root root - d /var/usrlocal/man 0755 root root - d /var/usrlocal/sbin 0755 root root - d /var/usrlocal/share 0755 root root - d /var/usrlocal/src 0755 root root - d /var/mnt 0755 root root - d /run/media 0755 root root - . However, as of OSTree 2023.9 there is support for a root.transient model, which can increase compatibility in some scenarios. For more information, see man ostree-prepare-root.conf. Particularly note here the double indirection of /home. By default, each deployment will share the global toplevel /home directory on the physical root filesystem. It is then up to higher levels of management tools to keep /etc/passwd or equivalent synchronized between operating systems. Each deployment can easily be reconfigured to have its own home directory set simply by making /var/home a real directory. ", + "url": "/ostree/adapting-existing/#system-layout", + + "relUrl": "/adapting-existing/#system-layout" + },"23": { + "doc": "Adapting existing mainstream distributions", + "title": "Booting and initramfs technology", + "content": "OSTree comes with optional dracut+systemd integration code which follows this logic: . | Parse the ostree= kernel command line argument in the initramfs | Set up a read-only bind mount on /usr | Bind mount the deployment’s /sysroot to the physical / | Use mount(MS_MOVE) to make the deployment root appear to be the root filesystem | . After these steps, systemd switches root. If you are not using dracut or systemd, using OSTree should still be possible, but you will have to write the integration code. See the existing sources in src/switchroot as a reference. Patches to support other initramfs technologies and init systems, if sufficiently clean, will likely be accepted upstream. A further specific note regarding sysvinit: OSTree used to support recording device files such as the /dev/initctl FIFO, but no longer does. It’s recommended to just patch your initramfs to create this at boot. ", + "url": "/ostree/adapting-existing/#booting-and-initramfs-technology", + + "relUrl": "/adapting-existing/#booting-and-initramfs-technology" + },"24": { + "doc": "Adapting existing mainstream distributions", + "title": "System users and groups", + "content": "Unlike traditional package systems, OSTree trees contain numeric uid and gids (the same is true of e.g. OCI). Furthermore, OSTree does not have a %post type mechanism where useradd could be invoked. In order to ship an OS that contains both system users and users dynamically created on client machines, you will need to choose a solution for /etc/passwd. The core problem is that if you add a user to the system for a daemon, the OSTree upgrade process for /etc will simply notice that because /etc/passwd differs from the previous default, it will keep the modified config file, and your new OS user will not be visible. First, consider using systemd DynamicUser=yes where applicable. This entirely avoids problems with static allocations. Static users and groups . For users which must be allocated statically (for example, they are used by setuid executables in /usr/bin, there are two primary wants to handle this. The nss-altfiles was created to pair with image-based update systems like OSTree, and is used by many operating systems and distributions today. More recently, nss-systemd gained support for statically allocated users and groups in a JSON format stored in /usr/lib/userdb. sysusers.d . Some users and groups can be assigned dynamically via sysusers.d. This means users and groups are maintained per-machine and may drift (unless statically assigned in sysusers). But this model is suitable for users and groups which must always be present, but do not have file content in the image. ", + "url": "/ostree/adapting-existing/#system-users-and-groups", + + "relUrl": "/adapting-existing/#system-users-and-groups" + },"25": { + "doc": "Adapting existing mainstream distributions", + "title": "Adapting existing package managers", + "content": "The largest endeavor is likely to be redesigning your distribution’s package manager to be on top of OSTree, particularly if you want to keep compatibility with the “old way” of installing into the physical /. This section will use examples from both dpkg and rpm as the author has familiarity with both; but the abstract concepts should apply to most traditional package managers. There are many levels of possible integration; initially, we will describe the most naive implementation which is the simplest but also the least efficient. We will assume here that the admin is booted into an OSTree-enabled system, and wants to add a set of packages. Many package managers store their state in /var; but since in the OSTree model that directory is shared between independent versions, the package database must first be found in the per-deployment /usr directory. It becomes read-only; remember, all upgrades involve constructing a new filesystem tree, so your package manager will also need to create a copy of its database. Most likely, if you want to continue supporting non-OSTree deployments, simply have your package manager fall back to the legacy /var location if the one in /usr is not found. To install a set of new packages (without removing any existing ones), enumerate the set of packages in the currently booted deployment, and perform dependency resolution to compute the complete set of new packages. Download and unpack these new packages to a temporary directory. Now, because we are merely installing new packages and not removing anything, we can make the major optimization of reusing our existing filesystem tree, and merely layering the composed filesystem tree of these new packages on top. A command like this: . ostree commit -b osname/releasename/description --tree=ref=$osname/$releasename/$description --tree=dir=/var/tmp/newpackages.13A8D0/ . will create a new commit in the $osname/$releasename/$description branch. The OSTree SHA256 checksum of all the files in /var/tmp/newpackages.13A8D0/ will be computed, but we will not re-checksum the present existing tree. In this layering model, earlier directories will take precedence, but files in later layers will silently override earlier layers. Then to actually deploy this tree for the next boot: ostree admin deploy $osname/$releasename/$description . This is essentially what rpm-ostree does to support its package layering model. ", + "url": "/ostree/adapting-existing/#adapting-existing-package-managers", + + "relUrl": "/adapting-existing/#adapting-existing-package-managers" + },"26": { + "doc": "Atomic Rollbacks", + "title": "Atomic Rollbacks", + "content": ". | Automatic rollbacks | Manual rollbacks | Rollbacks | Alternate rollback techniques | . ", + "url": "/ostree/atomic-rollbacks/", + + "relUrl": "/atomic-rollbacks/" + },"27": { + "doc": "Atomic Rollbacks", + "title": "Automatic rollbacks", + "content": "See greenboot for information on automatic rollbacks and how to integrate without your bootloader. ", + "url": "/ostree/atomic-rollbacks/#automatic-rollbacks", + + "relUrl": "/atomic-rollbacks/#automatic-rollbacks" + },"28": { + "doc": "Atomic Rollbacks", + "title": "Manual rollbacks", + "content": "Ostree writes bootloader entries that are interpreted by the bootloader. To manually rollback, for bootloaders such as GRUB and syslinux that have an interactive UI, it is possible to select a previous boot entry. In the case of an Android bootloader, a slot switch may be triggererd using an AB switching tool. This may be useful for testing purposes. ", + "url": "/ostree/atomic-rollbacks/#manual-rollbacks", + + "relUrl": "/atomic-rollbacks/#manual-rollbacks" + },"29": { + "doc": "Atomic Rollbacks", + "title": "Rollbacks", + "content": "+------------------------------------------------+ +------------------+ | | | | | | | (ostree:0) latest (multi-user.target) | | | Bootloader |--->+ root | | | | (ostree:1) latest - 1 (multi-user.target) | | | | | +------------------+ | +------------------------------------------------+ . Bootloaders have multiple boot entries to choose from after upgrade. On rollback, the bootloader will boot the “latest - 1” version, rather than the latest version of the OS. ", + "url": "/ostree/atomic-rollbacks/#rollbacks", + + "relUrl": "/atomic-rollbacks/#rollbacks" + },"30": { + "doc": "Atomic Rollbacks", + "title": "Alternate rollback techniques", + "content": "Below is an alternate technique to traditional AB switching that can be used. On rollback, an alternative boot target is used, rather than booting as default.target. +------------------------------------------------+ +------------------+ | | | | | | | (ostree:0) latest (multi-user.target) | | | Bootloader |--->+ root | | | | (ostree:1) latest - 1 (rescue.target) | | | | | +------------------+ | +------------------------------------------------+ . In this case, instead of rolling back to an older version, we also boot into an alternate systemd boot target. Here we will describe how you can put togther an alternate systemd boot target, using the built-in rescue.target as an example. Below is a rescue.service file, it essentially executes systemd-sulogin-shell rescue when this service is activated. rescue.service: . # SPDX-License-Identifier: LGPL-2.1-or-later # # This file is part of systemd. # # systemd is free software; you can redistribute it and/or modify it # under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation; either version 2.1 of the License, or # (at your option) any later version. [Unit] Description=Rescue Shell Documentation=man:sulogin(8) DefaultDependencies=no Conflicts=shutdown.target After=sysinit.target plymouth-start.service Before=shutdown.target [Service] Environment=HOME=/root WorkingDirectory=-/root ExecStartPre=-/usr/bin/plymouth --wait quit ExecStart=-/usr/lib/systemd/systemd-sulogin-shell rescue Type=idle StandardInput=tty-force StandardOutput=inherit StandardError=inherit KillMode=process IgnoreSIGPIPE=no SendSIGHUP=yes . Below is a rescue.target file, it is reached once rescue.service is complete. rescue.target: . # SPDX-License-Identifier: LGPL-2.1-or-later # # This file is part of systemd. # # systemd is free software; you can redistribute it and/or modify it # under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation; either version 2.1 of the License, or # (at your option) any later version. [Unit] Description=Rescue Mode Documentation=man:systemd.special(7) Requires=sysinit.target rescue.service After=sysinit.target rescue.service AllowIsolate=yes . This is a simple bash script, it checks whether ostree admin status -D is not-default and if it is, it notifies systemd to alternatively boot into rescue.target. In the happy path, when we have booted the latest version ostree admin status -D would output default. ostree-rollback-to-rescue: . #!/usr/bin/bash set -euo pipefail if [ \"$(ostree admin status -D)\" = \"not-default\" ]; then exec systemctl --no-block isolate rescue.target fi . This is a systemd service file that runs ostree-rollback-to-rescue early in the boot sequence, it is essential that this service is run early to ensure we don’t execute a full boot sequence, hence options DefaultDependencies=no and Before= are used. ostree-rollback-to-rescue.service . [Unit] Description=OSTree rollback to rescue DefaultDependencies=no OnFailure=emergency.target OnFailureJobMode=replace-irreversibly After=initrd-root-fs.target initrd-fs.target initrd.target boot.mount Before=cryptsetup.target integritysetup.target remote-fs.target slices.target swap.target veritysetup.target [Service] Type=oneshot ExecStart=/usr/sbin/ostree-rollback-to-rescue [Install] WantedBy=sysinit.target . ", + "url": "/ostree/atomic-rollbacks/#alternate-rollback-techniques", + + "relUrl": "/atomic-rollbacks/#alternate-rollback-techniques" + },"31": { + "doc": "Atomic Upgrades", + "title": "Atomic Upgrades", + "content": ". | You can turn off the power anytime you want… | Simple upgrades via HTTP | Upgrades via external tools (e.g. package managers) | Assembling a new deployment directory | Atomically swapping boot configuration | The bootversion | The /ostree/boot directory | . ", + "url": "/ostree/atomic-upgrades/", + + "relUrl": "/atomic-upgrades/" + },"32": { + "doc": "Atomic Upgrades", + "title": "You can turn off the power anytime you want…", + "content": "OSTree is designed to implement fully atomic and safe upgrades; more generally, atomic transitions between lists of bootable deployments. If the system crashes or you pull the power, you will have either the old system, or the new one. ", + "url": "/ostree/atomic-upgrades/#you-can-turn-off-the-power-anytime-you-want", + + "relUrl": "/atomic-upgrades/#you-can-turn-off-the-power-anytime-you-want" + },"33": { + "doc": "Atomic Upgrades", + "title": "Simple upgrades via HTTP", + "content": "First, the most basic model OSTree supports is one where it replicates pre-generated filesystem trees from a server over HTTP, tracking exactly one ref, which is stored in the .origin file for the deployment. The command ostree admin upgrade implements this. To begin a simple upgrade, OSTree fetches the contents of the ref from the remote server. Suppose we’re tracking a ref named exampleos/buildmain/x86_64-runtime. OSTree fetches the URL http://example.com/repo/refs/heads/exampleos/buildmain/x86_64-runtime, which contains a SHA256 checksum. This determines the tree to deploy, and /etc will be merged from currently booted tree. If we do not have this commit, then we perform a pull process. At present (without static deltas), this involves quite simply just fetching each individual object that we do not have, asynchronously. Put in other words, we only download changed files (zlib-compressed). Each object has its checksum validated and is stored in /ostree/repo/objects/. Once the pull is complete, we have downloaded all the objects that we need to perform a deployment. ", + "url": "/ostree/atomic-upgrades/#simple-upgrades-via-http", + + "relUrl": "/atomic-upgrades/#simple-upgrades-via-http" + },"34": { + "doc": "Atomic Upgrades", + "title": "Upgrades via external tools (e.g. package managers)", + "content": "As mentioned in the introduction, OSTree is also designed to allow a model where filesystem trees are computed on the client. It is completely agnostic as to how those trees are generated; they could be computed with traditional packages, packages with post-deployment scripts on top, or built by developers directly from revision control locally, etc. At a practical level, most package managers today (dpkg and rpm) operate “live” on the currently booted filesystem. The way they could work with OSTree is to, instead, take the list of installed packages in the currently booted tree, and compute a new filesystem from that. A later chapter describes in more details how this could work: Adapting Existing Systems. For the purposes of this section, let’s assume that we have a newly generated filesystem tree stored in the repo (which shares storage with the existing booted tree). We can then move on to checking it back out of the repo into a deployment. ", + "url": "/ostree/atomic-upgrades/#upgrades-via-external-tools-eg-package-managers", + + "relUrl": "/atomic-upgrades/#upgrades-via-external-tools-eg-package-managers" + },"35": { + "doc": "Atomic Upgrades", + "title": "Assembling a new deployment directory", + "content": "Given a commit to deploy, OSTree first allocates a directory for it. This is of the form /boot/loader/entries/ostree-$stateroot-$checksum.$serial.conf. The $serial is normally 0, but if a given commit is deployed more than once, it will be incremented. This is supported because the previous deployment may have configuration in /etc that we do not want to use or overwrite. Now that we have a deployment directory, a 3-way merge is performed between the (by default) currently booted deployment’s /etc, its default configuration, and the new deployment (based on its /usr/etc). How it works is: . | Files in the currently booted deployment’s /etc which were modified from the default /usr/etc (of the same deployment) are retained. | Files in the currently booted deployment’s /etc which were not modified from the default /usr/etc (of the same deployment) are upgraded to the new defaults from the new deployment’s /usr/etc. | . Roughly, this means that as soon as you modify or add a file in /etc, this file will be propagated forever as is (though there is a corner-case, where if your modification eventually exactly matches a future default file, then the file will go back to following future default updates from that point on). You can use ostree admin config-diff to see the differences between your booted deployment’s /etc and the OSTree defaults. A command like diff {/usr,}/etc will additional print line-level differences. ", + "url": "/ostree/atomic-upgrades/#assembling-a-new-deployment-directory", + + "relUrl": "/atomic-upgrades/#assembling-a-new-deployment-directory" + },"36": { + "doc": "Atomic Upgrades", + "title": "Atomically swapping boot configuration", + "content": "At this point, a new deployment directory has been created as a hardlink farm; the running system is untouched, and the bootloader configuration is untouched. We want to add this deployment to the “deployment list”. To support a more general case, OSTree supports atomic transitioning between arbitrary sets of deployments, with the restriction that the currently booted deployment must always be in the new set. In the normal case, we have exactly one deployment, which is the booted one, and we want to add the new deployment to the list. A more complex command might allow creating 100 deployments as part of one atomic transaction, so that one can set up an automated system to bisect across them. ", + "url": "/ostree/atomic-upgrades/#atomically-swapping-boot-configuration", + + "relUrl": "/atomic-upgrades/#atomically-swapping-boot-configuration" + },"37": { + "doc": "Atomic Upgrades", + "title": "The bootversion", + "content": "OSTree allows swapping between boot configurations by implementing the “swapped directory pattern” in /boot. This means it is a symbolic link to one of two directories /ostree/boot.[0|1]. To swap the contents atomically, if the current version is 0, we create /ostree/boot.1, populate it with the new contents, then atomically swap the symbolic link. Finally, the old contents can be garbage collected at any point. ", + "url": "/ostree/atomic-upgrades/#the-bootversion", + + "relUrl": "/atomic-upgrades/#the-bootversion" + },"38": { + "doc": "Atomic Upgrades", + "title": "The /ostree/boot directory", + "content": "However, we want to optimize for the case where the set of kernel/initramfs/devicetree sets is the same between both the old and new deployment lists. This happens when doing an upgrade that does not include the kernel; think of a simple translation update. OSTree optimizes for this case because on some systems /boot may be on a separate medium such as flash storage not optimized for significant amounts of write traffic. Related to this, modern OSTree has support for having /boot be a read-only mount by default - it will automatically remount read-write just for the portion of time necessary to update the bootloader configuration. To implement this, OSTree also maintains the directory /ostree/boot.$bootversion, which is a set of symbolic links to the deployment directories. The $bootversion here must match the version of /boot. However, in order to allow atomic transitions of this directory, this is also a swapped directory, so just like /boot, it has a version of 0 or 1 appended. Each bootloader entry has a special ostree= argument which refers to one of these symbolic links. This is parsed at runtime in the initramfs. ", + "url": "/ostree/atomic-upgrades/#the-ostreeboot-directory", + + "relUrl": "/atomic-upgrades/#the-ostreeboot-directory" + },"39": { + "doc": "Handling access to authenticated remote repositories", + "title": "Handling access to authenticated remote repositories", + "content": ". | Using mutual TLS | Using basic authentication | Using cookies | . There is no default concept of an “ostree server”; ostree expects to talk to a generic webserver, so any tool and technique applicable for generic HTTP can also apply to fetching content via OSTree’s builtin HTTP client. ", + "url": "/ostree/authenticated-repos/", + + "relUrl": "/authenticated-repos/" + },"40": { + "doc": "Handling access to authenticated remote repositories", + "title": "Using mutual TLS", + "content": "The tls-client-cert-path and tls-client-key-path expose the underlying HTTP code for mutual TLS. Each device can be provisioned with a secret key which grants it access to the webserver. ", + "url": "/ostree/authenticated-repos/#using-mutual-tls", + + "relUrl": "/authenticated-repos/#using-mutual-tls" + },"41": { + "doc": "Handling access to authenticated remote repositories", + "title": "Using basic authentication", + "content": "The client supports HTTP basic authentication, but this has well-known management drawbacks. ", + "url": "/ostree/authenticated-repos/#using-basic-authentication", + + "relUrl": "/authenticated-repos/#using-basic-authentication" + },"42": { + "doc": "Handling access to authenticated remote repositories", + "title": "Using cookies", + "content": "Since this pull request ostree supports adding cookies to a remote configuration. This can be used with e.g. Amazon CloudFront. ", + "url": "/ostree/authenticated-repos/#using-cookies", + + "relUrl": "/authenticated-repos/#using-cookies" + },"43": { + "doc": "Bootloaders", + "title": "Bootloaders", + "content": ". | OSTree and bootloaders | OSTree and grub | OSTree and aboot | GRUB and os-prober | Anaconda | bootupd | . ", + "url": "/ostree/bootloaders/", + + "relUrl": "/bootloaders/" + },"44": { + "doc": "Bootloaders", + "title": "OSTree and bootloaders", + "content": "The intended design of OSTree is that it just writes new files into /boot/loader/entries. There is a legacy GRUB script (shipped on Fedora as ostree-grub2) that is intended only for the cases where the system GRUB does not support the blscfg verb. In the happy path then, the flow of an OS update is just: . | ostree writes a new set of files in /boot/loader/entries (during ostree-finalize-staged.service on system shutdown) | On system start, GRUB reads those files | . And that’s it. ", + "url": "/ostree/bootloaders/#ostree-and-bootloaders", + + "relUrl": "/bootloaders/#ostree-and-bootloaders" + },"45": { + "doc": "Bootloaders", + "title": "OSTree and grub", + "content": "For historical reasons, OSTree defaults to detecting the bootloader; if some GRUB files are present then OSTree will default to executing grub2-mkconfig. ", + "url": "/ostree/bootloaders/#ostree-and-grub", + + "relUrl": "/bootloaders/#ostree-and-grub" + },"46": { + "doc": "Bootloaders", + "title": "OSTree and aboot", + "content": "The Android bootloader is another bootloader than may be used with ostree. It still uses the files in /boot/loader/entries as metadata, but the boootloader does not read these files. Android bootloaders package their kernel+initramfs+cmdline+dtb in a signed binary blob called an Android Boot Image. This binary blob then is written to either partition boot_a or boot_b depending on which slot is suitable. Android bootloaders by design inject kargs into the cmdline, some patches may be required in the Android bootloader implementation to ensure that the firmware does not switch between system_a and system_b partitions by populating a root= karg, or that a ro karg that is incompatible with ostree is not inserted. Conversly leaving the androidboot.slot_suffix= karg injecting functionality is required but this is commonplace for any Android Bootloader that does AB updates. We have two accompanying scripts that work with this type of environment: . aboot-update is used to generate Android Boot Images to be delivered to the client. aboot-deploy reads what the current slot is according to the androidboot.slot_suffix= karg, writes to the alternate boot_a or boot_b slot and sets a symlink either /ostree/root.a or /ostree/root.b so that it is known which userspace directory to boot into based on the androidboot.slot_suffix= karg, on subsequent boots. +-----------------------------+ +---------------------------------+ | +------------------+ | | firmware appends: | | | +--->+ boot_a partition +--->+ | androidboot.slot_suffix=_a | | /ostree/root.a | | +------------------+ | | or | system_a partition | | +------------------+ | | androidboot.slot_suffix=_b | | /ostree/root.b | +--->+ boot_b partition +--->+ | to cmdline | | | | +------------------+ | +-----------------------------+ +---------------------------------+ . ", + "url": "/ostree/bootloaders/#ostree-and-aboot", + + "relUrl": "/bootloaders/#ostree-and-aboot" + },"47": { + "doc": "Bootloaders", + "title": "GRUB and os-prober", + "content": "A specific component of GRUB that can significantly impede the reliability of OS updates is the os-prober aspect, which scans all system block devices. If one doesn’t care about dual booting, avoiding this is a good idea. ", + "url": "/ostree/bootloaders/#grub-and-os-prober", + + "relUrl": "/bootloaders/#grub-and-os-prober" + },"48": { + "doc": "Bootloaders", + "title": "Anaconda", + "content": "Until very recently, the Anaconda project only supported setting up the bootloader (e.g. GRUB) on its own, which requires grub2-mkconfig etc. As of recently, Anaconda now supports bootupd. ", + "url": "/ostree/bootloaders/#anaconda", + + "relUrl": "/bootloaders/#anaconda" + },"49": { + "doc": "Bootloaders", + "title": "bootupd", + "content": "As of recently, the bootupd project ships static grub configs and in this case, the sysroot.bootloader should be set to none (except on s390x). And assuming that the system grub has the blscfg support, which it does on Fedora derivatives per above. ", + "url": "/ostree/bootloaders/#bootupd", + + "relUrl": "/bootloaders/#bootupd" + },"50": { + "doc": "Writing a buildsystem and managing repositories", + "title": "Writing a buildsystem and managing repositories", + "content": ". | Build vs buy | Initializing | Writing your own OSTree buildsystem | Constructing trees from unions | Migrating content between repositories | More sophisticated repository management | . OSTree is not a package system. It does not directly support building source code. Rather, it is a tool for transporting and managing content, along with package-system independent aspects like bootloader management for updates. We’ll assume here that we’re planning to generate commits on a build server, then have client systems replicate it. Doing client-side assembly is also possible of course, but this discussion will focus primarily on server-side concerns. ", + "url": "/ostree/buildsystem-and-repos/", + + "relUrl": "/buildsystem-and-repos/" + },"51": { + "doc": "Writing a buildsystem and managing repositories", + "title": "Build vs buy", + "content": "Therefore, you need to either pick an existing tool for writing content into an OSTree repository, or write your own. An example tool is rpm-ostree - it takes as input RPMs, and commits them (currently oriented for server-side, but aiming to do client-side too). ", + "url": "/ostree/buildsystem-and-repos/#build-vs-buy", + + "relUrl": "/buildsystem-and-repos/#build-vs-buy" + },"52": { + "doc": "Writing a buildsystem and managing repositories", + "title": "Initializing", + "content": "For this initial discussion, we’re assuming you have a single archive repository: . mkdir repo ostree --repo=repo init --mode=archive . You can export this via a static webserver, and configure clients to pull from it. ", + "url": "/ostree/buildsystem-and-repos/#initializing", + + "relUrl": "/buildsystem-and-repos/#initializing" + },"53": { + "doc": "Writing a buildsystem and managing repositories", + "title": "Writing your own OSTree buildsystem", + "content": "There exist many, many systems that basically follow this pattern: . $pkg --installroot=/path/to/tmpdir install foo bar baz $imagesystem commit --root=/path/to/tmpdir . For various values of $pkg such as yum, apt-get, etc., and values of $imagesystem could be simple tarballs, Amazon Machine Images, ISOs, etc. Now obviously in this document, we’re going to talk about the situation where $imagesystem is OSTree. The general idea with OSTree is that wherever you might store a series of tarballs for applications or OS images, OSTree is likely going to be better. For example, it supports GPG signatures, binary deltas, writing bootloader configuration, etc. OSTree does not include a package/component build system simply because there already exist plenty of good ones - rather, it is intended to provide an infrastructure layer. The above mentioned rpm-ostree compose tree chooses RPM as the value of $pkg - so binaries are built as RPMs, then committed as a whole into an OSTree commit. But let’s discuss building our own. If you’re just experimenting, it’s quite easy to start with the command line. We’ll assume for this purpose that you have a build process that outputs a directory tree - we’ll call this tool $pkginstallroot (which could be yum --installroot or debootstrap, etc.). Your initial prototype is going to look like: . $pkginstallroot /path/to/tmpdir ostree --repo=repo commit -s 'build' -b exampleos/x86_64/standard --tree=dir=/path/to/tmpdir . Alternatively, if your build system can generate a tarball, you can commit that tarball into OSTree. For example, OpenEmbedded can output a tarball, and one can commit it via: . ostree commit -s 'build' -b exampleos/x86_64/standard --tree=tar=myos.tar . ", + "url": "/ostree/buildsystem-and-repos/#writing-your-own-ostree-buildsystem", + + "relUrl": "/buildsystem-and-repos/#writing-your-own-ostree-buildsystem" + },"54": { + "doc": "Writing a buildsystem and managing repositories", + "title": "Constructing trees from unions", + "content": "The above is a very simplistic model, and you will quickly notice that it’s slow. This is because OSTree has to re-checksum and recompress the content each time it’s committed. (Most of the CPU time is spent in compression which gets thrown away if the content turns out to be already stored). A more advanced approach is to store components in OSTree itself, then union them, and recommit them. At this point, we recommend taking a look at the OSTree API, and choose a programming language supported by GObject Introspection to write your buildsystem scripts. Python may be a good choice, or you could choose custom C code, etc. For the purposes of this tutorial we will use shell script, but it’s strongly recommended to choose a real programming language for your build system. Let’s say that your build system produces separate artifacts (whether those are RPMs, zip files, or whatever). These artifacts should be the result of make install DESTDIR= or similar. Basically equivalent to RPMs/debs. Further, in order to make things fast, we will need a separate bare-user repository in order to perform checkouts quickly via hardlinks. We’ll then export content into the archive repository for use by client systems. mkdir build-repo ostree --repo=build-repo init --mode=bare-user . You can begin committing those as individual branches: . ostree --repo=build-repo commit -b exampleos/x86_64/bash --tree=tar=bash-4.2-bin.tar.gz ostree --repo=build-repo commit -b exampleos/x86_64/systemd --tree=tar=systemd-224-bin.tar.gz . Set things up so that whenever a package changes, you redo the commit with the new package version - conceptually, the branch tracks the individual package versions over time, and defaults to “latest”. This isn’t required - one could also include the version in the branch name, and have metadata outside to determine “latest” (or the desired version). Now, to construct our final tree: . rm -rf exampleos-build for package in bash systemd; do ostree --repo=build-repo checkout -U --union exampleos/x86_64/${package} exampleos-build done # Set up a \"rofiles-fuse\" mount point; this ensures that any processes # we run for post-processing of the tree don't corrupt the hardlinks. mkdir -p mnt rofiles-fuse exampleos-build mnt # Now run global \"triggers\", generate cache files: ldconfig -r mnt (Insert other programs here) fusermount -u mnt ostree --repo=build-repo commit -b exampleos/x86_64/standard --link-checkout-speedup exampleos-build . There are a number of interesting things going on here. The major architectural change is that we’re using --link-checkout-speedup. This is a way to tell OSTree that our checkout is made via hardlinks, and to scan the repository in order to build up a reverse (device, inode) -> checksum mapping. In order for this mapping to be accurate, we needed the rofiles-fuse to ensure that any changed files had new inodes (and hence a new checksum). ", + "url": "/ostree/buildsystem-and-repos/#constructing-trees-from-unions", + + "relUrl": "/buildsystem-and-repos/#constructing-trees-from-unions" + },"55": { + "doc": "Writing a buildsystem and managing repositories", + "title": "Migrating content between repositories", + "content": "Now that we have content in our build-repo repository (in bare-user mode), we need to move the exampleos/x86_64/standard branch content into the repository just named repo (in archive mode) for export, which will involve zlib compression of new objects. We likely want to generate static deltas after that as well. Let’s copy the content: . ostree --repo=repo pull-local build-repo exampleos/x86_64/standard . Clients can now incrementally download new objects - however, this would also be a good time to generate a delta from the previous commit. ostree --repo=repo static-delta generate exampleos/x86_64/standard . ", + "url": "/ostree/buildsystem-and-repos/#migrating-content-between-repositories", + + "relUrl": "/buildsystem-and-repos/#migrating-content-between-repositories" + },"56": { + "doc": "Writing a buildsystem and managing repositories", + "title": "More sophisticated repository management", + "content": "Next, see Repository Management for the next steps in managing content in OSTree repositories. ", + "url": "/ostree/buildsystem-and-repos/#more-sophisticated-repository-management", + + "relUrl": "/buildsystem-and-repos/#more-sophisticated-repository-management" + },"57": { + "doc": "Using composefs with OSTree", + "title": "Using composefs with OSTree", + "content": ". | composefs . | Enabling composefs (unsigned) | composefs configuration | Injecting composefs digests | Signatures | . | Requirements | Status | Compatiblity | Comparison with other approaches | Further references | . ", + "url": "/ostree/composefs/", + + "relUrl": "/composefs/" + },"58": { + "doc": "Using composefs with OSTree", + "title": "composefs", + "content": "The composefs project is a new hybrid Linux stacking filesystem that provides many benefits when used for bootable host systems, such as a strong story for integrity. At the current time, integration of composefs and ostree is experimental. This issue tracks the latest status. Enabling composefs (unsigned) . When building a disk image or to transition an existing system, run: . ostree config --repo=/ostree/repo set ex-integrity.composefs true . This will ensure that any future deployments (e.g. created by ostree admin upgrade) have a .ostree.cfs file in the deployment directory which is a mountable composefs metadata file, with a “backing store” directory that is shared with the current /ostree/repo/objects. composefs configuration . The ostree-prepare-root binary will look for ostree/prepare-root.conf in /etc and /usr/lib in the initramfs. Using that configuration file you can enable composefs, and specify an Ed25519 public key to validate the booted commit. See the manpage for ostree-prepare-root for details of how to configure it. Injecting composefs digests . When generating an OSTree commit, there is a CLI switch --generate-composefs-metadata and a corresponding C API ostree_repo_commit_add_composefs_metadata. This will inject the composefs digest as metadata into the ostree commit under a metadata key ostree.composefs.v0. Because an OSTree commit can be signed, this allows covering the composefs fsverity digest with a signature. Signatures . If a commit is signed with an Ed25519 private key (see ostree --sign), and composefs.keyfile is specified in prepare-root.conf, then the initrd will find the commit being booted in the system repo and validate its signature against the public key. It will then ensure that the composefs digest being booted has an fs-verity digest matching the one in the commit. This allows a fully trusted read-only /usr. The exact usage of the signature is up to the user, but a common way to use it with transient keys. This is done like this: . | Generate a new keypair before each build | Embed the public key in the initrd that is part of the commit. | Ensure the initrd has a prepare-root.conf with [composefs] enabled=signed, and either use keypath or inject /etc/ostree/initramfs-root-binding.key; for more see man ostree-prepare-root | After committing, run ostree --sign with the private key. | Throw away the private key. | . When a transient key is used this way, that ties the initrd with the userspace part from the commit. This means each initrd can only boot the very same userspace it was made for. For example, if an older version of the OS has a security flaw, you can’t boot a new fixed (signed) initrd and have it boot the older userspace with the flaw. ", + "url": "/ostree/composefs/#composefs", + + "relUrl": "/composefs/#composefs" + },"59": { + "doc": "Using composefs with OSTree", + "title": "Requirements", + "content": "The current default composefs integration in ostree does not have any requirements from the underlying kernel and filesystem other than having the following kernel options set: . | CONFIG_OVERLAY_FS | CONFIG_BLK_DEV_LOOP | CONFIG_EROFS_FS | . At the current time, there are no additional userspace runtime requirements. ", + "url": "/ostree/composefs/#requirements", + + "relUrl": "/composefs/#requirements" + },"60": { + "doc": "Using composefs with OSTree", + "title": "Status", + "content": "IMPORTANT The integration with composefs is experimental and subject to change. Please try it and report issues but do not deploy to production systems yet. ", + "url": "/ostree/composefs/#status", + + "relUrl": "/composefs/#status" + },"61": { + "doc": "Using composefs with OSTree", + "title": "Compatiblity", + "content": "One issue that ostree users transitioning to composefs may hit is that it is no longer possible to add new toplevel directories via the chattr -i / && mkdir /somedir && chattr -i trick. A bit more on this in the following issues: . | https://github.com/coreos/rpm-ostree/issues/337 | https://github.com/ostreedev/ostree/pull/2681 | . However, users who were doing things like this probably want to enable the root.transient option; see man ostree-prepare-root which will allow this (but also change other behaviors too). ", + "url": "/ostree/composefs/#compatiblity", + + "relUrl": "/composefs/#compatiblity" + },"62": { + "doc": "Using composefs with OSTree", + "title": "Comparison with other approaches", + "content": "There is also support for using IMA with ostree. In short, composefs provides much stronger and more efficient integrity: . | composefs validates an entire filesystem tree, not just individual files | composefs makes files actually read-only, whereas IMA does not by default | composefs uses fs-verity which does on-demand verification (IMA by default does a full readahead of every file accessed, though IMA can also use fs-verity as a backend) | . ", + "url": "/ostree/composefs/#comparison-with-other-approaches", + + "relUrl": "/composefs/#comparison-with-other-approaches" + },"63": { + "doc": "Using composefs with OSTree", + "title": "Further references", + "content": ". | https://github.com/containers/composefs | https://www.kernel.org/doc/html/next/filesystems/fsverity.html | . ", + "url": "/ostree/composefs/#further-references", + + "relUrl": "/composefs/#further-references" + },"64": { + "doc": "OSTree Contributing Tutorial", + "title": "OSTree Contributing Tutorial", + "content": "The following guide is about OSTree forking, building, adding a command, testing the command, and submitting the change. | Getting Started | Building OSTree . | Install Build Dependencies | OSTree Build Commands . | Notes | Tip | . | . | Testing a Build . | Testing in a Container | Testing in a Virtual Machine | . | Tutorial: Adding a basic builtin command to ostree . | Modifying OSTree | Adding a new API function to libostree | OSTree Tests | Submitting a Patch | Returning Workflow | . | . ", + "url": "/ostree/contributing-tutorial/", + + "relUrl": "/contributing-tutorial/" + },"65": { + "doc": "OSTree Contributing Tutorial", + "title": "Getting Started", + "content": "Fork https://github.com/ostreedev/ostree, then run the following commands. $ git clone https://github.com/<username>/ostree && cd ostree $ git remote add upstream https://github.com/ostreedev/ostree $ git checkout main $ git fetch upstream && git branch --set-upstream-to=upstream/main main . Make a branch from main for your patch. $ git checkout -b <name-of-branch> $ git branch --set-upstream-to=upstream/main <name-of-branch> . ", + "url": "/ostree/contributing-tutorial/#getting-started", + + "relUrl": "/contributing-tutorial/#getting-started" + },"66": { + "doc": "OSTree Contributing Tutorial", + "title": "Building OSTree", + "content": "Install Build Dependencies . Execute one of the following group commands as superuser depending on your machine’s package manager. For Fedora: . $ dnf install @buildsys-build dnf-plugins-core && \\ dnf builddep ostree . For CentOS: . $ yum install yum-utils dnf-plugins-core && \\ yum-builddep ostree . For Debian based distros: . $ apt-get update && \\ apt-get install build-essential && \\ apt-get build-dep ostree . build.sh will have a list of packages needed to build ostree. OSTree Build Commands . These are the basic commands to build OSTree. Depending on the OS that OSTree will be built for, the flags or options for ./autogen.sh and ./configure will vary. See ostree-build.sh in this tutorial below for specific commands to building OSTree for Fedora 28 and Fedora 28 Atomic Host. # optional: autogen.sh will run this if necessary git submodule update --init env NOCONFIGURE=1 ./autogen.sh # run ./configure if makefile does not exist ./configure make make install DESTDIR=/path/to/install/binary . Notes . Running git submodule update --init is optional since autogen.sh will check to see if one of the submodule files for example from libglnx/ or from bsdiff/ exists. Additionally, autogen.sh will check to see if the environment variable NOCONFIGURE is set. To run ./configure manually, run autogen in a modified environment as such, env NOCONFIGURE=1 ./autogen.sh. Otherwise, leave NOCONFIGURE empty and autogen.sh will run ./configure as part of the autogen.sh command when it executes. For more information on --prefix see Variables for Installation Directories. make install will generate files for /bin and /lib. If DESTDIR is unspecified then OSTree will be installed in the default directory i.e. /usr/local/bin and its static libraries in /usr/local/lib. Note that the /usr/local portion of the path can be changed using the --prefix option for ./configure. See this GNU guide on DESTDIR Staged Installs for more information. Tip . Make allows parallel execution of recipes. Use make -j<N> to speed up the build. <N> is typically $((2 * $(nproc))) for optimal performance, where nproc is the number of processing units (CPU cores) available. See page 106 of the GNU Make Manual for more information about the --jobs or -j option. ", + "url": "/ostree/contributing-tutorial/#building-ostree", + + "relUrl": "/contributing-tutorial/#building-ostree" + },"67": { + "doc": "OSTree Contributing Tutorial", + "title": "Testing a Build", + "content": "It is best practice to build software (definitely including ostree) in a container or virtual machine first. Testing in a Container . There are a variety of container engines available and many distributions have pre-packaged versions of e.g. Podman and Docker. If you choose to use Docker upstream, you may want to follow this post-installation guide for Docker. This will allow you to run Docker as a non-root user on a Linux based host machine. You will need to have pushed a remote git branch $REMOTE_BRANCH (see ostree-git.sh below) in order to pull your changes into a container. The example below uses Docker to manage containers. Save the contents of this Dockerfile somewhere on your machine: . # this pulls the fedora 28 image FROM registry.fedoraproject.org/fedora:28 # install ostree dependencies RUN dnf update -y && \\ dnf -y install @buildsys-build dnf-plugins-core && \\ dnf -y builddep ostree && \\ dnf clean all # clone ostree and update main branch COPY ostree-git.sh / RUN ../ostree-git.sh # builds ostree + any additional commands COPY ostree-build.sh / # entry into the container will start at this directory WORKDIR /ostree # run the following as `/bin/sh -c` # or enter the container to execute ./ostree-build.sh RUN ../ostree-build.sh . Save the following bash scripts in the same directory as the Dockerfile. Then change the mode bit of these files so that they are executable, by running chmod +x ostree-git.sh ostree-build.sh . #!/bin/bash # ostree-git.sh # Clone ostree and update main branch set -euo pipefail # Set $USERNAME to your GitHub username here. USERNAME=\"\" # clone your fork of the OSTree repo, this will be in the \"/\" directory git clone https://github.com/$USERNAME/ostree.git cd ostree # Add upstream as remote and update main branch git checkout main git remote add upstream https://github.com/ostreedev/ostree.git git pull --rebase upstream main . #!/bin/bash # ostree-build.sh # Build and test OSTree set -euo pipefail # $REMOTE_BRANCH is the name of the remote branch in your # repository that contains changes (e.g. my-patch). REMOTE_BRANCH=\"\" # fetch updates from origin # origin url should be your forked ostree repository git fetch origin # go to branch with changes # if this branch already exists then checkout that branch exit_code=\"$(git checkout --track origin/$REMOTE_BRANCH; echo $?)\" if [[ \"$exit_code\" == 1 ]] then echo \"This branch:\" $REMOTE_BRANCH \"is not a remote branch.\" exit fi # make sure branch with changes is up-to-date git pull origin $REMOTE_BRANCH # build OSTree commands for Fedora 28 and Fedora 28 Atomic Host ./autogen.sh --prefix=/usr --libdir=/usr/lib64 --sysconfdir=/etc ./configure --prefix=/usr make -j$((2 * $(nproc))) make install # any additional commands go here . Build the container . Run docker build in the same directory of the Dockerfile like so: . $ docker build -t ostree-fedora-test . When this build is done, the -t option tags the image as ostree-fedora-test. Note: Do not forget the dot . at the end of the above command which specifies the location of the Dockerfile. You will see ostree-fedora-test listed when running docker images: . REPOSITORY TAG IMAGE ID CREATED SIZE ostree-fedora-test latest 817c04cc3656 1 day ago 978MB . Entering the Container . To start the ostree-fedora-test container, run: . $ docker run -it --rm --entrypoint /bin/sh --name ostree-testing ostree-fedora-test . Note: . --rm option tells Docker to automatically clean up the container and remove the file system when the container exits. Otherwise remove it manually by running docker rm <container name>. The state of the container will not be saved when the shell prompt exits. Best practice is modify the Dockerfile to modify the image. Testing in a Container Workflow . | Edit the changes to OSTree on your local machine. | git add to stage the changed files, git commit and then git push origin <local-branch>:<remote-branch>. | Testing on a new container vs. Testing on an existing container: . If the ostree-testing container was newly built right after your changes have been committed, then the container’s build of ostree should contain your changes. Else: Within the ostree-testing container, run ../ostree-build.sh in the ostree directory. This will pull in changes from your branch and create a new ostree build. | make install will install OSTree in the default location i.e. /usr/..in a Fedora 28 container. | Test ostree. | . Testing in a Virtual Machine . To create a Fedora 28 Atomic Host Vagrant VM, run the following commands: . $ mkdir atomic && cd atomic $ vagrant init fedora/28-atomic-host && vagrant up . An option is to use rsync to transfer ostree files to a Vagrant VM. To find the IP address of a Vagrant VM, run vagrant ssh-config in the same directory as the Vagrantfile. Steps to rsync files to test an ostree build: . | Copy the contents of your public ssh key on your host machine e.g. id_rsa.pub to /home/vagrant/.ssh/authorized_keys on the VM. | Run sudo su, followed by ssh localhost then press Ctrl+c to exit from the decision prompt. This will create the .ssh directory with the right permissions. | Using Vagrant as the user, run sudo cp ~/.ssh/authorized_keys /root/.ssh/. So that user root has the the same login credentials. | To override the Read-only file system warning, run sudo ostree admin unlock. | <ostree-install-dir> will serve as the local install location for ostree and the path to this directory should be absolute when specified in DESTDIR. | Set rsync to sync changes in /etc and /usr from <ostree-install-dir>/ on the host to the VM: . $ rsync -av <ostree-install-dir>/etc/ root@<ip-address>:/etc $ rsync -av <ostree-install-dir>/usr/ root@<ip-address>:/usr . Using option -n will execute the commands as a trial, which is helpful to list the files that will be synced. | Run the commands in step 6 each time a new ostree build is executed to update the change. Running ls -lt in the directory where the changed file is expected, is a simple way to check when a particular file was last modified. Proceed to the test changes ostree with the most recent changes. | . ", + "url": "/ostree/contributing-tutorial/#testing-a-build", + + "relUrl": "/contributing-tutorial/#testing-a-build" + },"68": { + "doc": "OSTree Contributing Tutorial", + "title": "Tutorial: Adding a basic builtin command to ostree", + "content": "Modifying OSTree . This will add a command which prints Hello OSTree! when ostree hello-ostree is entered. | Create a file in src/ostree named ot-builtin-hello-ostree.c. Code that lives in here belongs to OSTree, and uses functionality from libostree. | Add the following to ot-builtin-hello-ostree.c: . #include \"config.h\" #include \"ot-main.h\" #include \"ot-builtins.h\" #include \"ostree.h\" #include \"otutil.h\" // Structure for options such as ostree hello-ostree --option. static GOptionEntry options[] = { { NULL }, }; gboolean ostree_builtin_hello_ostree (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error) { g_autoptr(OstreeRepo) repo = NULL; // Creates new command context, ready to be parsed. // Input to g_option_context_new shows when running ostree <command> --help g_autoptr(GOptionContext) context = g_option_context_new (\"\"); // Parses the command context according to the ostree CLI. if (!ostree_option_context_parse (context, options, &argc, &argv, invocation, &repo, cancellable, error)) return FALSE; g_print(\"Hello OSTree!\\n\"); return TRUE; } . This defines the functionality for hello-ostree. Now we have to make sure the CLI can refer to the execution function, and that autotools knows to build this file. Note: libostree codebase supports C99 features. | Add the following in src/ostree/main.c: . { \"hello-ostree\", // The name of the command OSTREE_BUILTIN_FLAG_NO_REPO, // Flag not to require the `--repo` argument, see \"ot-main.h\" ostree_builtin_hello_ostree, // Execution function for the command \"Print hello message\" }, // Short description to appear when `ostree hello-ostree --help` is entered . | Add a macro for the function declaration of ostree_builtin_hello_ostree, in ot-builtins.h: . BUILTINPROTO(hello_ostree); . This makes the function definition visible to the CLI. | Configure automake to include ot-builtin-hello-ostree.c in the build, by adding an entry in Makefile-ostree.am under ostree_SOURCES: . src/ostree/ot-builtin-hello-ostree.c \\ . | Rebuild ostree: . $ make && make install DESTDIR=/path/to/install/the/content . | Execute the new ostree binary, from where you installed it: . $ ostree hello-ostree Hello OSTree! . | . Adding a new API function to libostree . This will add a new API function ostree_kernel_args_foo() in src/libostree/ostree-kernel-args.c. | Add the following to src/libostree/ostree-kernel-args.h: _OSTREE_PUBLIC gboolean ostree_kernel_args_foo (const char *arg, GCancellable *cancellable, GError **error); . | Add the following to ostree-kernel-args.c: /** * ostree_kernel_args_foo: * @arg: Description of the arg * * Description of the function * * Since: $NEWVERSION //The new libostree version, for example 2022.5 **/ gboolean ostree_kernel_args_foo (const char *arg, GCancellable *cancellable, GError **error) { //Add code here } . | Add the following to src/libostree/libostree-devel.sym: LIBOSTREE_$NEWVERSION { // The new libostree version global: ostree_kernel_args_foo; // Function name } LIBOSTREE_$LASTSTABLE; // The last stable libostree version . | Add the following to Makefile-libostree.am: if BUILDOPT_IS_DEVEL_BUILD symbol_files += $(top_srcdir)/src/libostree/libostree-devel.sym endif . | Add function name ostree_kernel_args_foo to apidoc/ostree-sections.txt under <FILE>ostree-kernel-args</FILE>. | Call function ostree_kernel_args_foo() in your code. | . OSTree Tests . Tests for OSTree are done by shell scripting, by running OSTree commands and examining output. These steps will go through adding a test for hello-ostree. | Create a file in tests called test-hello-ostree.sh. | Add the following to test-hello-ostree.sh: . set -euo pipefail # Ensure the test will not silently fail . $(dirname $0)/libtest.sh # Make libtest.sh functions available echo \"1..1\" # Declare which test is being run out of how many pushd ${test_tmpdir} ${CMD_PREFIX} ostree hello-ostree > hello-output.txt assert_file_has_content hello-output.txt \"Hello OSTree!\" popd echo \"ok hello ostree\" # Indicate test success . Many tests require a fake repository setting up (as most OSTree commands require --repo to be specified). See test-pull-depth.sh for an example of this setup. | Configure automake to include test-hello-ostree.sh in the build, by adding an entry in Makefile-tests.am under _installed_or_uninstalled_test_scripts: . tests/test-hello-ostree.sh \\ . | Make sure test-hello-ostree.sh has executable permissions! . $ chmod +x tests/test-hello-ostree.sh . | Run the test: . $ make check TESTS=\"tests/test-hello-ostree.sh\" . Multiple tests can be specified: make check TESTS=\"test1 test2 ...\". To run all tests, use make check. Hopefully, the test passes! The following will be printed: . PASS: tests/test-hello-ostree.sh 1 hello ostree ============================================================================ Testsuite summary for libostree 2018.8 ============================================================================ # TOTAL: 1 # PASS: 1 # SKIP: 0 # XFAIL: 0 # FAIL: 0 # XPASS: 0 # ERROR: 0 ============================================================================ . | . Submitting a Patch . After you have committed your changes and tested, you are ready to submit your patch! . You should make sure your commits are placed on top of the latest changes from upstream/main: . $ git pull --rebase upstream main . To submit your patch, open a pull request from your forked repository. Most often, you’ll be merging into ostree:main from <username>:<branch name>. If some of your changes are complete and you would like feedback, you may also open a pull request that has WIP (Work In Progress) in the title. Before a pull request is considered merge ready, your commit messages should fall within the specified guideline. See Commit message style. See CONTRIBUTING.md for information on squashing commits, and alternative options to submit patches. Returning Workflow . When returning to work on a patch, it is recommended to update your fork with the latest changes in the upstream main branch. If creating a new branch: . $ git checkout main $ git pull upstream main $ git checkout -b <name-of-patch> . If continuing on a branch already created: . $ git checkout <name-of-patch> $ git pull --rebase upstream main . ", + "url": "/ostree/contributing-tutorial/#tutorial-adding-a-basic-builtin-command-to-ostree", + + "relUrl": "/contributing-tutorial/#tutorial-adding-a-basic-builtin-command-to-ostree" + },"69": { + "doc": "Deployments", + "title": "Deployments", + "content": ". | Overview . | “stateroot” (AKA “osname”): Group of deployments that share /var | Contents of a deployment | Staged deployments | The system /boot | . | . ", + "url": "/ostree/deployment/", + + "relUrl": "/deployment/" + },"70": { + "doc": "Deployments", + "title": "Overview", + "content": "Built on top of the OSTree versioning filesystem core is a layer that knows how to deploy, parallel install, and manage Unix-like operating systems (accessible via ostree admin). The core content of these operating systems are treated as read-only, but they transparently share storage. A deployment is physically located at a path of the form /ostree/deploy/$stateroot/deploy/$checksum. OSTree is designed to boot directly into exactly one deployment at a time; each deployment is intended to be a target for chroot() or equivalent. “stateroot” (AKA “osname”): Group of deployments that share /var . Each deployment is grouped in exactly one “stateroot” (also known as an “osname”); the former term is preferred. From above, you can see that a stateroot is physically represented in the /ostree/deploy/$stateroot directory. For example, OSTree can allow parallel installing Debian in /ostree/deploy/debian and Red Hat Enterprise Linux in /ostree/deploy/rhel (subject to operating system support, present released versions of these operating systems may not support this). Each stateroot has exactly one copy of the traditional Unix /var, stored physically in /ostree/deploy/$stateroot/var. OSTree provides support tools for systemd to create a Linux bind mount that ensures the booted deployment sees the shared copy of /var. OSTree does not touch the contents of /var. Operating system components such as daemon services are required to create any directories they require there at runtime (e.g. /var/cache/$daemonname), and to manage upgrading data formats inside those directories. Contents of a deployment . A deployment begins with a specific commit (represented as a SHA256 hash) in the OSTree repository in /ostree/repo. This commit refers to a filesystem tree that represents the underlying basis of a deployment. For short, we will call this the “tree”, to distinguish it from the concept of a deployment. First, the tree must include a kernel (and optionally an initramfs). The current standard locations for these are /usr/lib/modules/$kver/vmlinuz and /usr/lib/modules/$kver/initramfs.img. The “boot checksum” will be computed automatically. This follows the current Fedora kernel layout, and is the current recommended path. However, older versions of libostree don’t support this; you may need to also put kernels in the previous (legacy) paths, which are vmlinuz(-.*)?-$checksum in either /boot or /usr/lib/ostree-boot. The checksum should be a SHA256 hash of the kernel contents; it must be pre-computed before storing the kernel in the repository. Optionally, the directory can also contain an initramfs, stored as initramfs(-.*)?-$checksum and/or a device tree, stored as devicetree(-.*)?-$checksum. If an initramfs or devicetree exist, the checksum must include all of the kernel, initramfs and devicetree contents. OSTree will use this to determine which kernels are shared. The rationale for this is to avoid computing checksums on the client by default. The deployment should not have a traditional UNIX /etc; instead, it should include /usr/etc. This is the “default configuration”. When OSTree creates a deployment, it performs a 3-way merge using the old default configuration, the active system’s /etc, and the new default configuration. In the final filesystem tree for a deployment then, /etc is a regular writable directory. Besides the exceptions of /var and /etc then, the rest of the contents of the tree are checked out as hard links into the repository. It’s strongly recommended that operating systems ship all of their content in /usr, but this is not a hard requirement. Finally, a deployment may have a .origin file, stored next to its directory. This file tells ostree admin upgrade how to upgrade it. At the moment, OSTree only supports upgrading a single refspec. However, in the future OSTree may support a syntax for composing layers of trees, for example. Staged deployments . As mentioned above, when OSTree creates a new deployment, a 3-way merge is done to update its /etc. Depending on the nature of the system, this can cause an issue: if a user or program modifies the booted /etc after the pending deployment is created but before rebooting, those modifications will be lost. OSTree does not do a second /etc merge on reboot. To counter this, OSTree supports staged deployments. In this flow, deployments are created using e.g. ostree admin upgrade --stage on the CLI. The new deployment is still created when the command is invoked, but the 3-way /etc merge is delayed until the system is rebooted or shut down. Additionally, updating the bootloader is also delayed. This is done by the ostree-finalize-staged.service systemd unit. The main disadvantage of this approach is that rebooting can take longer and the failure mode can be confusing (the machine will reboot into the same deployment). In systems where the workload is well-understood and not subject to the /etc issue above, it may be better to not stage deployments. The system /boot . While OSTree parallel installs deployments cleanly inside the /ostree directory, ultimately it has to control the system’s /boot directory. The way this works is via the Boot Loader Specification, which is a standard for bootloader-independent drop-in configuration files. When a tree is deployed, it will have a configuration file generated of the form /boot/loader/entries/ostree-$stateroot-$checksum.$serial.conf. This configuration file will include a special ostree= kernel argument that allows the initramfs to find (and chroot() into) the specified deployment. At present, not all bootloaders implement the BootLoaderSpec, so OSTree contains code for some of these to regenerate native config files (such as /boot/syslinux/syslinux.conf) based on the entries. ", + "url": "/ostree/deployment/#overview", + + "relUrl": "/deployment/#overview" + },"71": { + "doc": "OSTree data formats", + "title": "OSTree data formats", + "content": ". | On the topic of “smart servers” | The archive format | archive efficiency | Aside: bare formats | Static deltas | Static delta repository layout | Static delta internal structure . | The delta superblock | . | A delta part | Fallback objects | . ", + "url": "/ostree/formats/", + + "relUrl": "/formats/" + },"72": { + "doc": "OSTree data formats", + "title": "On the topic of “smart servers”", + "content": "One really crucial difference between OSTree and git is that git has a “smart server”. Even when fetching over https://, it isn’t just a static webserver, but one that e.g. dynamically computes and compresses pack files for each client. In contrast, the author of OSTree feels that for operating system updates, many deployments will want to use simple static webservers, the same target most package systems were designed to use. The primary advantages are security and compute efficiency. Services like Amazon S3 and CDNs are a canonical target, as well as a stock static nginx server. ", + "url": "/ostree/formats/#on-the-topic-of-smart-servers", + + "relUrl": "/formats/#on-the-topic-of-smart-servers" + },"73": { + "doc": "OSTree data formats", + "title": "The archive format", + "content": "In the repo section, the concept of objects was introduced, where file/content objects are checksummed and managed individually. (Unlike a package system, which operates on compressed aggregates). The archive format simply gzip-compresses each content object. Metadata objects are stored uncompressed. This means that it’s easy to serve via static HTTP. Note: the repo config file still uses the historical term archive-z2 as mode. But this essentially indicates the modern archive format. When you commit new content, you will see new .filez files appearing in objects/. ", + "url": "/ostree/formats/#the-archive-format", + + "relUrl": "/formats/#the-archive-format" + },"74": { + "doc": "OSTree data formats", + "title": "archive efficiency", + "content": "The advantages of archive: . | It’s easy to understand and implement | Can be served directly over plain HTTP by a static webserver | Clients can download/unpack updates incrementally | Space efficient on the server | . The biggest disadvantage of this format is that for a client to perform an update, one HTTP request per changed file is required. In some scenarios, this actually isn’t bad at all, particularly with techniques to reduce HTTP overhead, such as HTTP/2. In order to make this format work well, you should design your content such that large data that changes infrequently (e.g. graphic images) are stored separately from small frequently changing data (application code). Other disadvantages of archive: . | It’s quite bad when clients are performing an initial pull (without HTTP/2), | One doesn’t know the total size (compressed or uncompressed) of content before downloading everything | . ", + "url": "/ostree/formats/#archive-efficiency", + + "relUrl": "/formats/#archive-efficiency" + },"75": { + "doc": "OSTree data formats", + "title": "Aside: bare formats", + "content": "The most common operation is to pull from a remote archive repository into a local one. This latter is not compressed on disk. In other words, pulling to a local repository is similar to unpacking (but not installing) the content of an RPM/deb package. The bare repository format is the simplest one. In this mode regular files are directly stored to disk, and all metadata (e.g. uid/gid and xattrs) is reflected to the filesystem. It allows further direct access to content and metadata, but it may require elevated privileges when writing objects to the repository. The bare-user format is a bit special in that the uid/gid and xattrs from the content are ignored. This is primarily useful if you want to have the same OSTree-managed content that can be run on a host system or an unprivileged container. Similarly, the bare-split-xattrs format is a special mode where xattrs are stored as separate repository objects, and not directly reflected to the filesystem. This is primarily useful when transporting xattrs through lossy environments (e.g. tar streams and containerized environments). It also allows carrying security-sensitive xattrs (e.g. SELinux labels) out-of-band without involving OS filesystem logic. ", + "url": "/ostree/formats/#aside-bare-formats", + + "relUrl": "/formats/#aside-bare-formats" + },"76": { + "doc": "OSTree data formats", + "title": "Static deltas", + "content": "OSTree itself was originally focused on a continuous delivery model, where client systems are expected to update regularly. However, many OS vendors would like to supply content that’s updated e.g. once a month or less often. For this model, we can do a lot better to support batched updates than a basic archive repo. However, we still want to preserve the model of “static webserver only”. Given this, OSTree has gained the concept of a “static delta”. These deltas are targeted to be a delta between two specific commit objects, including “bsdiff” and “rsync-style” deltas within a content object. Static deltas also support from NULL, where the client can more efficiently download a commit object from scratch - this is mostly useful when using OSTree for containers, rather than OS images. For OS images, one tends to download an installer ISO or qcow2 image which is a single file that contains the tree data already. Effectively, we’re spending server-side storage (and one-time compute cost), and gaining efficiency in client network bandwidth. ", + "url": "/ostree/formats/#static-deltas", + + "relUrl": "/formats/#static-deltas" + },"77": { + "doc": "OSTree data formats", + "title": "Static delta repository layout", + "content": "Since static deltas may not exist, the client first needs to attempt to locate one. Suppose a client wants to retrieve commit ${new} while currently running ${current}. In order to save space, these two commits are “modified base64” - the / character is replaced with _. Like the commit objects, a “prefix directory” is used to make management easier for filesystem tools. A delta is named $(mbase64 $from)-$(mbase64 $to), for example GpTyZaVut2jXFPWnO4LJiKEdRTvOw_mFUCtIKW1NIX0-L8f+VVDkEBKNc1Ncd+mDUrSVR4EyybQGCkuKtkDnTwk, which in SHA256 format is 1a94f265a56eb768d714f5a73b82c988a11d453bcec3f985502b48296d4d217d-2fc7fe5550e410128d73535c77e98352b495478132c9b4060a4b8ab640e74f09. Finally, the actual content can be found in deltas/$fromprefix/$fromsuffix-$to. ", + "url": "/ostree/formats/#static-delta-repository-layout", + + "relUrl": "/formats/#static-delta-repository-layout" + },"78": { + "doc": "OSTree data formats", + "title": "Static delta internal structure", + "content": "A delta is itself a directory. Inside, there is a file called superblock which contains metadata. The rest of the files will be integers bearing packs of content. The file format of static deltas should be currently considered an OSTree implementation detail. Obviously, nothing stops one from writing code which is compatible with OSTree today. However, we would like the flexibility to expand and change things, and having multiple codebases makes that more problematic. Please contact the authors with any requests. That said, one critical thing to understand about the design is that delta payloads are a bit more like “restricted programs” than they are raw data. There’s a “compilation” phase which generates output that the client executes. This “updates as code” model allows for multiple content generation strategies. The design of this was inspired by that of Chromium: ChromiumOS Autoupdate. The delta superblock . The superblock contains: . | arbitrary metadata | delta generation timestamp | the new commit object | An array of recursive deltas to apply | An array of per-part metadata, including total object sizes (compressed and uncompressed), | An array of fallback objects | . Let’s define a delta part, then return to discuss details: . ", + "url": "/ostree/formats/#static-delta-internal-structure", + + "relUrl": "/formats/#static-delta-internal-structure" + },"79": { + "doc": "OSTree data formats", + "title": "A delta part", + "content": "A delta part is a combination of a raw blob of data, plus a very restricted bytecode that operates on it. Say for example two files happen to share a common section. It’s possible for the delta compilation to include that section once in the delta data blob, then generate instructions to write out that blob twice when generating both objects. Realistically though, it’s very common for most of a delta to just be “stream of new objects” - if one considers it, it doesn’t make sense to have too much duplication inside operating system content at this level. So then, what’s more interesting is that OSTree static deltas support a per-file delta algorithm called bsdiff that most notably works well on executable code. The current delta compiler scans for files with matching basenames in each commit that have a similar size, and attempts a bsdiff between them. (It would make sense later to have a build system provide a hint for this - for example, files within a same package). A generated bsdiff is included in the payload blob, and applying it is an instruction. ", + "url": "/ostree/formats/#a-delta-part", + + "relUrl": "/formats/#a-delta-part" + },"80": { + "doc": "OSTree data formats", + "title": "Fallback objects", + "content": "It’s possible for there to be large-ish files which might be resistant to bsdiff. A good example is that it’s common for operating systems to use an “initramfs”, which is itself a compressed filesystem. This “internal compression” defeats bsdiff analysis. For these types of objects, the delta superblock contains an array of “fallback objects”. These objects aren’t included in the delta parts - the client simply fetches them from the underlying .filez object. ", + "url": "/ostree/formats/#fallback-objects", + + "relUrl": "/formats/#fallback-objects" + },"81": { + "doc": "Using Linux IMA with OSTree", + "title": "Using Linux IMA with OSTree", + "content": ". | Linux IMA | IMA signatures and OSTree checksum | Signing . | Generating a key | Signing a commit | Applying a policy | Linux EVM | . | Further references | . ", + "url": "/ostree/ima/", + + "relUrl": "/ima/" + },"82": { + "doc": "Using Linux IMA with OSTree", + "title": "Linux IMA", + "content": "The Linux Integrity Measurement Architecture provides a mechanism to cryptographically sign the digest of a regular file, and policies can be applied to e.g. require that code executed by the root user have a valid signed digest. The alignment between Linux IMA and ostree is quite strong. OSTree provides a content-addressable object store, where files are intended to be immutable. This is implemented with a basic read-only bind mount. While IMA does not actually prevent mutating files, any changed (or unsigned) files would (depending on policy) not be readable or executable. ", + "url": "/ostree/ima/#linux-ima", + + "relUrl": "/ima/#linux-ima" + },"83": { + "doc": "Using Linux IMA with OSTree", + "title": "IMA signatures and OSTree checksum", + "content": "Mechanically, IMA signatures appear as a security.ima extended attribute on the file. This is a signed digest of just the file content (and not any metadata) . OSTree’s checksums in contrast include not just the file content, but also metadata such as uid, gid and mode and extended attributes; . Together, this means that adding an IMA signature to a file in the OSTree model appears as a new object (with a new digest). A nice property is that this enables the transactional addition (or removal) of IMA signatures. However, adding IMA signatures to files that were previously unsigned also today duplicates disk space. ", + "url": "/ostree/ima/#ima-signatures-and-ostree-checksum", + + "relUrl": "/ima/#ima-signatures-and-ostree-checksum" + },"84": { + "doc": "Using Linux IMA with OSTree", + "title": "Signing", + "content": "To apply IMA signatures to an OSTree commit, there is an ima-sign command implemented currently in the ostree-rs-ext project. Generating a key . There is documentation for this in man evmctl and the upstream IMA page; we will not replicate it here. Signing a commit . ima-sign requires 4 things: . | An OSTree repository (could be any mode; archive or e.g. bare-user) | A ref or commit digest (e.g. exampleos/x86_64/stable) | A digest algorithm (usually sha256, but you may use e.g. sha512 as well) | An RSA private key | . You can then add IMA signatures to all regular files in the commit: . $ ostree-ext-cli ima-sign --repo=repo exampleos/x86_64/stable sha256 /path/to/key.pem . Many different choices are possible for the signing model. For example, your build system could store individual components/packages in their own ostree refs, and sign them at build time. This would avoid re-signing all binaries when creating production builds. Although note you still likely want to sign generated artifacts from unioning individual components, such as a dpkg/rpm database or equivalent and cache files such as the ldconfig and GTK+ icon caches, etc. Applying a policy . Signing a commit by itself will have little to no effect. You will also need to include in your builds an IMA policy. Linux EVM . The EVM subsystem builds on IMA, and adds another signature which covers most file data, such as the uid, gid and mode and selected security-relevant extended attributes. This is quite close to the ostree native checksum - the ordering of the fields is different so the checksums are physically different, but logically they are very close. However, the focus of the EVM design seems to mostly be on machine-specific signatures with keys stored in a TPM. Note that doing this on a per-machine basis would add a new security.evm extended attribute, and crucially that changes the ostree digest - so from ostree’s perspective, these objects will appear corrupt. In the future, ostree may learn to ignore the presence of security.evm extended attributes. There is also some support for “portable” EVM signatures - by default, EVM signatures also include the inode number and generation which are inherently machine-specific. A future ostree enhancement may instead also focus on supporting signing commits with these “portable” EVM signatures in addition to IMA. ", + "url": "/ostree/ima/#signing", + + "relUrl": "/ima/#signing" + },"85": { + "doc": "Using Linux IMA with OSTree", + "title": "Further references", + "content": ". | https://sourceforge.net/p/linux-ima/wiki/Home/ | https://en.opensuse.org/SDB:Ima_evm | https://wiki.gentoo.org/wiki/Integrity_Measurement_Architecture | https://fedoraproject.org/wiki/Changes/Signed_RPM_Contents | https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_monitoring_and_updating_the_kernel/enhancing-security-with-the-kernel-integrity-subsystem_managing-monitoring-and-updating-the-kernel | . ", + "url": "/ostree/ima/#further-references", + + "relUrl": "/ima/#further-references" + },"86": { + "doc": "libostree", + "title": "libostree", + "content": ". | Operating systems and distributions using OSTree | Distribution build tools | Projects linking to libostree | Language bindings | Building | API Reference | Manual Pages | Contact and discussion forums | Contributing | Licensing | . This project is now known as “libostree”, though it is still appropriate to use the previous name: “OSTree” (or “ostree”). The focus is on projects which use libostree’s shared library, rather than users directly invoking the command line tools (except for build systems). However, in most of the rest of the documentation, we will use the term “OSTree”, since it’s slightly shorter, and changing all documentation at once is impractical. We expect to transition to the new name over time. As implied above, libostree is both a shared library and suite of command line tools that combines a “git-like” model for committing and downloading bootable filesystem trees, along with a layer for deploying them and managing the bootloader configuration. The core OSTree model is like git in that it checksums individual files and has a content-addressed-object store. It’s unlike git in that it “checks out” the files via hardlinks, and they thus need to be immutable to prevent corruption. Therefore, another way to think of OSTree is that it’s just a more polished version of Linux VServer hardlinks. Features: . | Transactional upgrades and rollback for the system | Replicating content incrementally over HTTP via GPG signatures and “pinned TLS” support | Support for parallel installing more than just 2 bootable roots | Binary history on the server side (and client) | Introspectable shared library API for build and deployment systems | Flexible support for multiple branches and repositories, supporting projects like Flatpak which use libostree for applications, rather than hosts. | . ", + "url": "/ostree/", + + "relUrl": "/" + },"87": { + "doc": "libostree", + "title": "Operating systems and distributions using OSTree", + "content": "Apertis uses libostree for their host system as well as Flatpak. See update documentation and apertis-update-manager . Endless OS uses libostree for their host system as well as Flatpak. See their eos-updater and deb-ostree-builder projects. For Debian/apt, see also https://github.com/stb-tester/apt2ostree and the LWN article Merkle trees and build systems. Fedora derivatives use rpm-ostree (noted below); there are 4 variants using OSTree: . | Fedora CoreOS | Fedora Silverblue | Fedora Kinoite | Fedora IoT | . Red Hat Enterprise Linux CoreOS is a derivative of Fedora CoreOS, used in OpenShift 4. The machine-config-operator manages upgrades. RHEL CoreOS is also the successor to RHEL Atomic Host, which uses rpm-ostree as well. Red Hat In-Vehicle Operating System (RHIVOS) is a derivative of CentOS Automotive Stream Distribution that uses OSTree, it’s closest Fedora derivative is Fedora IoT although it was created as it’s own distribution. GNOME Continuous is where OSTree was born - as a high performance continuous delivery/testing system for GNOME. GNOME OS is a testing OS that uses libostree for their host system as well as Flatpak. Liri OS has the option to install their distribution using ostree. Torizon OS is a Linux distribution for embedded systems that updates via OSTree images delivered via Uptane and aktualizr. ", + "url": "/ostree/#operating-systems-and-distributions-using-ostree", + + "relUrl": "/#operating-systems-and-distributions-using-ostree" + },"88": { + "doc": "libostree", + "title": "Distribution build tools", + "content": "meta-updater is a layer available for OpenEmbedded systems. QtOTA is Qt’s over-the-air update framework which uses libostree. The BuildStream build and integration tool supports importing and exporting from libostree repos. fedora-iot/otto is a tool that helps ship ostree commits inside Docker/OCI containers and run a webserver to serve the commits. Fedora coreos-assembler is the build tool used to generate Fedora CoreOS derivatives. debos is a tool-chain for simplifying the process of building a Debian-based OS image. gardenlinux/ostree-image-builder is a sample for building Debian-based OS images. It is not production ready but it might be useful to get started. ", + "url": "/ostree/#distribution-build-tools", + + "relUrl": "/#distribution-build-tools" + },"89": { + "doc": "libostree", + "title": "Projects linking to libostree", + "content": "rpm-ostree is used by the Fedora-derived operating systems listed above. It is a full hybrid image/package system. By default it uses libostree to atomically replicate a base OS (all dependency resolution is done on the server), but it supports “package layering”, where additional RPMs can be layered on top of the base. This brings a “best of both worlds”” model for image and package systems. eos-updater is a daemon that implements updates on EndlessOS. Flatpak uses libostree for desktop application containers. Unlike most of the other systems here, Flatpak does not use the “libostree host system” aspects (e.g. bootloader management), just the “git-like hardlink dedup”. For example, Flatpak supports a per-user OSTree repository. aktualizr is an Uptane-conformant software update client library intended for use in automotive and other security-sensitive embedded devices. It uses OSTree to manage the OS of the host device by default. ", + "url": "/ostree/#projects-linking-to-libostree", + + "relUrl": "/#projects-linking-to-libostree" + },"90": { + "doc": "libostree", + "title": "Language bindings", + "content": "libostree is accessible via GObject Introspection; any language which has implemented the GI binding model should work. For example, Both pygobject and gjs are known to work and further are actually used in libostree’s test suite today. Some bindings take the approach of using GI as a lower level and write higher level manual bindings on top; this is more common for statically compiled languages. Here’s a list of such bindings: . | ostree-go | ostree-rs | . ", + "url": "/ostree/#language-bindings", + + "relUrl": "/#language-bindings" + },"91": { + "doc": "libostree", + "title": "Building", + "content": "Releases are available as GPG signed git tags, and most recent versions support extended validation using git-evtag. However, in order to build from a git clone, you must update the submodules. If you’re packaging OSTree and want a tarball, I recommend using a “recursive git archive” script. There are several available online; this code in OSTree is an example. Once you have a git clone or recursive archive, building is the same as almost every autotools project: . git submodule update --init env NOCONFIGURE=1 ./autogen.sh ./configure --prefix=... make make install DESTDIR=/path/to/dest . ", + "url": "/ostree/#building", + + "relUrl": "/#building" + },"92": { + "doc": "libostree", + "title": "API Reference", + "content": "The libostree API documentation is available in Reference. ", + "url": "/ostree/#api-reference", + + "relUrl": "/#api-reference" + },"93": { + "doc": "libostree", + "title": "Manual Pages", + "content": "The ostree manual pages are available in Manual. ", + "url": "/ostree/#manual-pages", + + "relUrl": "/#manual-pages" + },"94": { + "doc": "libostree", + "title": "Contact and discussion forums", + "content": "There is also an #ostree channel on Libera.Chat as well as enabled Github discussions. ", + "url": "/ostree/#contact-and-discussion-forums", + + "relUrl": "/#contact-and-discussion-forums" + },"95": { + "doc": "libostree", + "title": "Contributing", + "content": "See Contributing. ", + "url": "/ostree/#contributing", + + "relUrl": "/#contributing" + },"96": { + "doc": "libostree", + "title": "Licensing", + "content": "The licensing for the code of libostree can be canonically found in the individual files; and the overall status in the COPYING file in the source. Currently, that’s LGPLv2+. This also covers the man pages and API docs. The license for the manual documentation in the doc/ directory is: SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) This is intended to allow use by Wikipedia and other projects. In general, files should have a SPDX-License-Identifier and that is canonical. ", + "url": "/ostree/#licensing", + + "relUrl": "/#licensing" + },"97": { + "doc": "OSTree Overview", + "title": "OSTree Overview", + "content": ". | Introduction | Hello World example | Comparison with “package managers” | Comparison with block/image replication | Atomic transitions between parallel-installable read-only filesystem trees | . ", + "url": "/ostree/introduction/", + + "relUrl": "/introduction/" + },"98": { + "doc": "OSTree Overview", + "title": "Introduction", + "content": "OSTree is an upgrade system for Linux-based operating systems that performs atomic upgrades of complete filesystem trees. It is not a package system; rather, it is intended to complement them. A primary model is composing packages on a server, and then replicating them to clients. The underlying architecture might be summarized as “git for operating system binaries”. It operates in userspace, and will work on top of any Linux filesystem. At its core is a git-like content-addressed object store with branches (or “refs”) to track meaningful filesystem trees within the store. Similarly, one can check out or commit to these branches. Layered on top of that is bootloader configuration, management of /etc, and other functions to perform an upgrade beyond just replicating files. You can use OSTree standalone in the pure replication model, but another approach is to add a package manager on top, thus creating a hybrid tree/package system. ", + "url": "/ostree/introduction/#introduction", + + "relUrl": "/introduction/#introduction" + },"99": { + "doc": "OSTree Overview", + "title": "Hello World example", + "content": "OSTree is mostly used as a library, but a quick tour of using its CLI tools can give a general idea of how it works at its most basic level. You can create a new OSTree repository using init: . $ ostree --repo=repo init . This will create a new repo directory containing your repository. Feel free to inspect it. Now, let’s prepare some data to add to the repo: . $ mkdir tree $ echo \"Hello world!\" > tree/hello.txt . We can now import our tree/ directory using the commit command: . $ ostree --repo=repo commit --branch=foo tree/ . This will create a new branch foo pointing to the full tree imported from tree/. In fact, we could now delete tree/ if we wanted to. To check that we indeed now have a foo branch, you can use the refs command: . $ ostree --repo=repo refs foo . We can also inspect the filesystem tree using the ls and cat commands: . $ ostree --repo=repo ls foo d00775 1000 1000 0 / -00664 1000 1000 13 /hello.txt $ ostree --repo=repo cat foo /hello.txt Hello world! . And finally, we can check out our tree from the repository: . $ ostree --repo=repo checkout foo tree-checkout/ $ cat tree-checkout/hello.txt Hello world! . ", + "url": "/ostree/introduction/#hello-world-example", + + "relUrl": "/introduction/#hello-world-example" + },"100": { + "doc": "OSTree Overview", + "title": "Comparison with “package managers”", + "content": "Because OSTree is designed for deploying core operating systems, a comparison with traditional “package managers” such as dpkg and rpm is illustrative. Packages are traditionally composed of partial filesystem trees with metadata and scripts attached, and these are dynamically assembled on the client machine, after a process of dependency resolution. In contrast, OSTree only supports recording and deploying complete (bootable) filesystem trees. It has no built-in knowledge of how a given filesystem tree was generated or the origin of individual files, or dependencies, descriptions of individual components. Put another way, OSTree only handles delivery and deployment; you will likely still want to include inside each tree metadata about the individual components that went into the tree. For example, a system administrator may want to know what version of OpenSSL was included in your tree, so you should support the equivalent of rpm -q or dpkg -L. The OSTree core emphasizes replicating read-only OS trees via HTTP, and where the OS includes (if desired) an entirely separate mechanism to install applications, stored in /var if they’re system global, or /home for per-user application installation. An example application mechanism is http://docker.io/ . However, it is entirely possible to use OSTree underneath a package system, where the contents of /usr are computed on the client. For example, when installing a package, rather than changing the currently running filesystem, the package manager could assemble a new filesystem tree that layers the new packages on top of a base tree, record it in the local OSTree repository, and then set it up for the next boot. To support this model, OSTree provides an (introspectable) C shared library. ", + "url": "/ostree/introduction/#comparison-with-package-managers", + + "relUrl": "/introduction/#comparison-with-package-managers" + },"101": { + "doc": "OSTree Overview", + "title": "Comparison with block/image replication", + "content": "OSTree shares some similarity with “dumb” replication and stateless deployments, such as the model common in “cloud” deployments where nodes are booted from an (effectively) readonly disk, and user data is kept on a different volumes. The advantage of “dumb” replication, shared by both OSTree and the cloud model, is that it’s reliable and predictable. But unlike many default image-based deployments, OSTree supports exactly two persistent writable directories that are preserved across upgrades: /etc and /var. Because OSTree operates at the Unix filesystem layer, it works on top of any filesystem or block storage layout; it’s possible to replicate a given filesystem tree from an OSTree repository into plain ext4, BTRFS, XFS, or in general any Unix-compatible filesystem that supports hard links. Note: OSTree will transparently take advantage of some BTRFS features if deployed on it. OSTree is orthogonal to virtualization mechanisms like AMIs and qcow2 images, though it’s most useful though if you plan to update stateful VMs in-place, rather than generating new images. In practice, users of “bare metal” configurations will find the OSTree model most useful. ", + "url": "/ostree/introduction/#comparison-with-blockimage-replication", + + "relUrl": "/introduction/#comparison-with-blockimage-replication" + },"102": { + "doc": "OSTree Overview", + "title": "Atomic transitions between parallel-installable read-only filesystem trees", + "content": "Another deeply fundamental difference between both package managers and image-based replication is that OSTree is designed to parallel-install multiple versions of multiple independent operating systems. OSTree relies on a new toplevel ostree directory; it can in fact parallel install inside an existing OS or distribution occupying the physical / root. On each client machine, there is an OSTree repository stored in /ostree/repo, and a set of “deployments” stored in /ostree/deploy/$STATEROOT/$CHECKSUM. Each deployment is primarily composed of a set of hardlinks into the repository. This means each version is deduplicated; an upgrade process only costs disk space proportional to the new files, plus some constant overhead. The model OSTree emphasizes is that the OS read-only content is kept in the classic Unix /usr; it comes with code to create a Linux read-only bind mount to prevent inadvertent corruption. There is exactly one /var writable directory shared between each deployment for a given OS. The OSTree core code does not touch content in this directory; it is up to the code in each operating system for how to manage and upgrade state. Finally, each deployment has its own writable copy of the configuration store /etc. On upgrade, OSTree will perform a basic 3-way diff, and apply any local changes to the new copy, while leaving the old untouched. ", + "url": "/ostree/introduction/#atomic-transitions-between-parallel-installable-read-only-filesystem-trees", + + "relUrl": "/introduction/#atomic-transitions-between-parallel-installable-read-only-filesystem-trees" + },"103": { + "doc": "Related Projects", + "title": "Related Projects", + "content": ". | Combining dpkg/rpm + (BTRFS/LVM) | ChromiumOS updater | Ubuntu Image Based Updates | Clear Linux Software update | casync | Mender.io | OLPC update | NixOS / Nix | Solaris IPS | Google servers (custom rsync-like approach, live updates) | Conary | bmap | Git | Conda | rpm-ostree | GNOME Continuous | Docker | Docker-related: Balena | Torizon Platform . | Torizon OS | TorizonCore Builder | Torizon Cloud | . | . OSTree is in many ways very evolutionary. It builds on concepts and ideas introduced from many different projects such as Systemd Stateless, Systemd Bootloader Spec, Chromium Autoupdate, the much older Fedora/Red Hat Stateless Project, Linux VServer and many more. As mentioned elsewhere, OSTree is strongly influenced by package manager designs as well. This page is not intended to be an exhaustive list of such projects, but we will try to keep it up to date, and relatively agnostic. Broadly speaking, projects in this area fall into two camps; either a tool to snapshot systems on the client side (dpkg/rpm + BTRFS/LVM), or a tool to compose on a server and replicate (ChromiumOS, Clear Linux). OSTree is flexible enough to do both. Note that this section of the documentation is almost entirely focused on the “ostree for host” model; the flatpak project uses libostree to store application data, distinct from the host system management model. ", + "url": "/ostree/related-projects/", + + "relUrl": "/related-projects/" + },"104": { + "doc": "Related Projects", + "title": "Combining dpkg/rpm + (BTRFS/LVM)", + "content": "In this approach, one uses a block/filesystem snapshot tool underneath the system package manager. The oVirt Node imgbased tool is an example of this approach, as are a few others below. Regarding BTRFS in particular - the OSTree author believes that Linux storage is a wide world, and while BTRFS is quite good, it is not everywhere now, nor will it be in the near future. There are other recently developed filesystems like f2fs, and Red Hat Enterprise Linux still defaults to XFS. Using a snapshot tool underneath a package manager does help significantly. In the rest of this text, we will use “BTRFS” as a mostly generic tool for filesystem snapshots. The obvious thing to do is layer BTRFS under dpkg/rpm, and have a separate subvolume for /home so rollbacks don’t lose your data. See e.g. Fedora BTRFS Rollback Feature. More generally, if you want to use BTRFS to roll back changes made by dpkg/rpm, you have to carefully set up the partition layout so that the files laid out by dpkg/rpm are installed in a subvolume to snapshot. This problem in many ways is addressed by the changes OSTree forces, such as putting all local state in /var (e.g. /usr/local -> /var/usrlocal). Then one can BTRFS snapshot /usr. This gets pretty far, except handling /etc is messy. This is something OSTree does well. In general, if one really tries to flesh out the BTRFS approach, a nontrivial middle layer of code between dpkg/rpm and BTRFS (or deep awareness of BTRFS in dpkg/rpm itself) will be required. A good example of this is the snapper.io project. The OSTree author believes that having total freedom at the block storage layer is better for general purpose operating systems. For example, the ability to choose dm-crypt per deployment is quite useful; not every site wants to pay the performance penalty. One can choose LVM or not, etc. Where applicable, OSTree does take advantage of copy-on-write/reflink features offered by the kernel for /etc. It uses the now generic ioctl(FICLONE) and copy_file_range(). Another major distinction between the default OSTree usage and package managers is whether updates are “online” or “offline” by default. The default OSTree design writes updates into a new root, leaving the running system unchanged. This means preparing updates is completely non-disruptive and safe - if the system runs out of disk space in the middle, it’s easy to recover. However, there is work in the rpm-ostree project to support online updates as well. OSTree supports using “bare-user” repositories, which do not require root to use. Using a filesystem-level layer without root is more difficult and would likely require a setuid helper or privileged service. Finally, see the next portion around ChromiumOS for why a hybrid but integrated package/image system improves on this. ", + "url": "/ostree/related-projects/#combining-dpkgrpm--btrfslvm", + + "relUrl": "/related-projects/#combining-dpkgrpm--btrfslvm" + },"105": { + "doc": "Related Projects", + "title": "ChromiumOS updater", + "content": "Many people who look at OSTree are most interested in using it as an updater for embedded or fixed-purpose systems, similar to use cases from the ChromiumOS updater. The ChromiumOS approach uses two partitions that are swapped via the bootloader. It has a very network-efficient update protocol, using a custom binary delta scheme between filesystem snapshots. This model even allows for switching filesystem types in an update. A major downside of this approach is that the OS size is doubled on disk always. In contrast, OSTree uses plain Unix hardlinks, which means it essentially only requires disk space proportional to the changed files, plus some small fixed overhead. This means with OSTree, one can easily have more than two trees (deployments). Another example is that the system OSTree repository could also be used for application containers. Finally, the author of OSTree believes that what one really wants for many cases is image replication with the ability to layer on some additional components (e.g. packages) - a hybrid model. This is what rpm-ostree is aiming to support. ", + "url": "/ostree/related-projects/#chromiumos-updater", + + "relUrl": "/related-projects/#chromiumos-updater" + },"106": { + "doc": "Related Projects", + "title": "Ubuntu Image Based Updates", + "content": "See https://wiki.ubuntu.com/ImageBasedUpgrades. Very architecturally similar to ChromeOS, although more interesting is discussion for supporting package installation on top, similar to rpm-ostree package layering. ", + "url": "/ostree/related-projects/#ubuntu-image-based-updates", + + "relUrl": "/related-projects/#ubuntu-image-based-updates" + },"107": { + "doc": "Related Projects", + "title": "Clear Linux Software update", + "content": "The Clear Linux Software update system is not very well documented. This mailing list post has some reverse-engineered design documentation. Like OSTree static deltas, it also uses bsdiff for network efficiency. More information will be filled in here over time. The OSTree author believes that at the moment, the “CL updater” is not truly atomic in the sense that because it applies updates live, there is a window where the OS root may be inconsistent. ", + "url": "/ostree/related-projects/#clear-linux-software-update", + + "relUrl": "/related-projects/#clear-linux-software-update" + },"108": { + "doc": "Related Projects", + "title": "casync", + "content": "The systemd casync project is relatively new. Currently, it is more of a storage library, and doesn’t support higher level logic for things like GPG signatures, versioning information, etc. This is mostly the OstreeRepo layer. Moving up to the OstreeSysroot level - things like managing the bootloader configuration, and most importantly implementing correct merging for /etc are missing. casync also is unaware of SELinux. OSTree is really today a shared library, and has been for quite some time. This has made it easy to build higher level projects such as rpm-ostree which has quite a bit more, such as a DBus API and other projects consume that, such as Cockpit. A major issue with casync today is that it doesn’t support garbage collection on the server side. OSTree’s GC works symmetrically on the server and client side. Broadly speaking, casync is a twist on the dual partition approach, and shares the general purpose disadvantages of those. ", + "url": "/ostree/related-projects/#casync", + + "relUrl": "/related-projects/#casync" + },"109": { + "doc": "Related Projects", + "title": "Mender.io", + "content": "Mender.io is another implementation of the dual partition approach. ", + "url": "/ostree/related-projects/#menderio", + + "relUrl": "/related-projects/#menderio" + },"110": { + "doc": "Related Projects", + "title": "OLPC update", + "content": "OSTree is basically a generalization of olpc-update, except using plain HTTP instead of rsync. OSTree has the notion of separate trees that one can track independently or parallel install, while still sharing storage via the hardlinked repository, whereas olpc-update uses version numbers for a single OS. OSTree has built-in plain old HTTP replication which can be served from a static webserver, whereas olpc-update uses rsync (more server load, but more efficient on the network side). The OSTree solution to improving network bandwidth consumption is via static deltas. See this comment for a comparison. ", + "url": "/ostree/related-projects/#olpc-update", + + "relUrl": "/related-projects/#olpc-update" + },"111": { + "doc": "Related Projects", + "title": "NixOS / Nix", + "content": "See NixOS. It was a very influential project for OSTree. NixOS and OSTree both support the idea of independent “roots” that are bootable. In NixOS, files in a package are accessed by a path depending on the checksums of package inputs (build dependencies) - see Nix store. However, OSTree uses a commit/deploy model - it isn’t tied to any particular directory layout, and you can put whatever data you want inside an OSTree, for example the standard FHS layout. A both positive and negative of the Nix model is that a change in the build dependencies (e.g. being built with a newer gcc), requires a cascading rebuild of everything. It’s good because it makes it easy to do massive system-wide changes such as gcc upgrades, and allows installing multiple versions of packages at once. However, a security update to e.g. glibc forces a rebuild of everything from scratch, and so Nix is not practical at scale. OSTree supports using a build system that just rebuilds individual components (packages) as they change, without forcing a rebuild of their dependencies. Nix automatically detects runtime package dependencies by scanning content for hashes. OSTree only supports only system-level images, and doesn’t do dependency management. Nix can store arbitrary files, using nix-store --add, but, more commonly, paths are added as the result of running a derivation file generated using the Nix language. OSTree is build-system agnostic; filesystem trees are committed using a simple C API, and this is the only way to commit files. OSTree automatically shares the storage of identical data using hard links into a content-addressed store. Nix can deduplicate using hard links as well, using the auto-optimise-store option, but this is not on by default, and Nix does not guarantee that all of its files are in the content-addressed store. OSTree provides a git-like command line interface for browsing the content-addressed store, while Nix does not have this functionality. Nix used to use the immutable bit to prevent modifications to /nix/store, but now it uses a read-only bind mount. The bind mount can be privately remounted, allowing per-process privileged write access. OSTree uses the immutable bit on the root of the deployment, and mounts /usr as read-only. NixOS supports switching OS images on-the-fly, by maintaining both booted-system and current-system roots. It is not clear how well this approach works. OSTree currently requries a reboot to switch images. Finally, NixOS supports installing user-specific packages from trusted repositories without requiring root, using a trusted daemon. Flatpak, based on OSTree, similarly has a policykit-based system helper that allows you to authenticate via polkit to install into the system repository. ", + "url": "/ostree/related-projects/#nixos--nix", + + "relUrl": "/related-projects/#nixos--nix" + },"112": { + "doc": "Related Projects", + "title": "Solaris IPS", + "content": "See Solaris IPS. Broadly, this is a similar design as to a combination of BTRFS+RPM/deb. There is a bootloader management system which combines with the snapshots. It’s relatively well thought through - however, it is a client-side system assembly. If one wants to image servers and replicate reliably, that’d be a different system. ", + "url": "/ostree/related-projects/#solaris-ips", + + "relUrl": "/related-projects/#solaris-ips" + },"113": { + "doc": "Related Projects", + "title": "Google servers (custom rsync-like approach, live updates)", + "content": "This paper talks about how Google was (at least at one point) managing updates for the host systems for some servers: Live Upgrading Thousands of Servers from an Ancient Red Hat Distribution to 10 Year Newer Debian Based One (USENIX LISA 2013) . ", + "url": "/ostree/related-projects/#google-servers-custom-rsync-like-approach-live-updates", + + "relUrl": "/related-projects/#google-servers-custom-rsync-like-approach-live-updates" + },"114": { + "doc": "Related Projects", + "title": "Conary", + "content": "See Conary Updates and Rollbacks. If rpm/dpkg are like CVS, Conary is closer to Subversion. It’s not bad, but e.g. its rollback model is rather ad-hoc and not atomic. It also is a fully client side system and doesn’t have an image-like replication with deltas. ", + "url": "/ostree/related-projects/#conary", + + "relUrl": "/related-projects/#conary" + },"115": { + "doc": "Related Projects", + "title": "bmap", + "content": "See bmap. A tool for optimized copying of disk images. Intended for offline use, so not directly comparable. ", + "url": "/ostree/related-projects/#bmap", + + "relUrl": "/related-projects/#bmap" + },"116": { + "doc": "Related Projects", + "title": "Git", + "content": "Although OSTree has been called “Git for Binaries”, and the two share the idea of a hashed content store, the implementation details are quite different. OSTree supports extended attributes and uses SHA256 instead of Git’s SHA1. It “checks out” files via hardlinks, rather than copying, and thus requires the checkout to be immutable. At the moment, OSTree commits may have at most one parent, as opposed to Git which allows an arbitrary number. Git uses a smart-delta protocol for updates, while OSTree uses 1 HTTP request per changed file, or can generate static deltas. ", + "url": "/ostree/related-projects/#git", + + "relUrl": "/related-projects/#git" + },"117": { + "doc": "Related Projects", + "title": "Conda", + "content": "Conda is an “OS-agnostic, system-level binary package manager and ecosystem”; although most well-known for its accompanying Python distribution anaconda, its scope has been expanding quickly. The package format is very similar to well-known ones such as RPM. However, unlike typical RPMs, the packages are built to be relocatable. Also, the package manager runs natively on Windows. Conda’s main advantage is its ability to install collections of packages into “environments” by unpacking them all to the same directory. Conda reduces duplication across environments using hardlinks, similar to OSTree’s sharing between deployments (although Conda uses package / file path instead of file hash). Overall, it is quite similar to rpm-ostree in functionality and scope. ", + "url": "/ostree/related-projects/#conda", + + "relUrl": "/related-projects/#conda" + },"118": { + "doc": "Related Projects", + "title": "rpm-ostree", + "content": "This builds on top of ostree to support building RPMs into OSTree images, and even composing RPMs on-the-fly using an overlay filesystem. It is being developed by Fedora, Red Hat, and CentOS as part of Project Atomic. ", + "url": "/ostree/related-projects/#rpm-ostree", + + "relUrl": "/related-projects/#rpm-ostree" + },"119": { + "doc": "Related Projects", + "title": "GNOME Continuous", + "content": "This is a service that incrementally rebuilds and tests GNOME on every commit. The need to make and distribute snapshots for this system was the original inspiration for ostree. ", + "url": "/ostree/related-projects/#gnome-continuous", + + "relUrl": "/related-projects/#gnome-continuous" + },"120": { + "doc": "Related Projects", + "title": "Docker", + "content": "It makes sense to compare OSTree and Docker as far as wire formats go. OSTree is not itself a container tool, but can be used as a transport/storage format for container tools. Docker has (at the time of this writing) two format versions (v1 and v2). v1 is deprecated, so we’ll look at format version 2. A Docker image is a series of layers, and a layer is essentially JSON metadata plus a tarball. The tarballs capture changes between layers, including handling deleting files in higher layers. Because the payload format is just tar, Docker hence captures (numeric) uid/gid and xattrs. This “layering” model is an interesting and powerful part of Docker, allowing different images to reference a shared base. OSTree doesn’t implement this natively, but it’s not difficult to implement in higher level tools. For example in flatpak, there’s a concept of a SDK and runtime, and it would make a lot of sense for the SDK to depend on the runtime, to avoid clients downloading data twice (even if it’s deduplicated on disk). That gets to an advantage of OSTree over Docker; OSTree checksums individual files (not tarballs), and uses this for deduplication. Docker (natively) only shares storage via layering. The biggest feature OSTree has over Docker though is support for (static) deltas, and even without pre-configured static deltas, the archive format has “natural” deltas. Particularly for a “base operating system”, one really wants on-wire deltas. It’d likely be possible to extend Docker with this concept. A core challenge both share is around metadata (particularly signing) and search/discovery (the ostree summary file doesn’t scale very well). One major issue Docker has is that it checksums compressed data, and furthermore the tar format is flexible, with multiple ways to represent data, making it hard to impossible to reassemble and verify from on-disk state. The tarsum effort was intended to address this, but it was not adopted in the end for v2. ", + "url": "/ostree/related-projects/#docker", + + "relUrl": "/related-projects/#docker" + },"121": { + "doc": "Related Projects", + "title": "Docker-related: Balena", + "content": "The Balena project forks Docker and aims to even use Docker/OCI format for the root filesystem, and adds wire deltas using librsync. See also discussion on libostree-list. ", + "url": "/ostree/related-projects/#docker-related-balena", + + "relUrl": "/related-projects/#docker-related-balena" + },"122": { + "doc": "Related Projects", + "title": "Torizon Platform", + "content": "Torizon is an open-source software platform that simplifies the development and maintenance of embedded Linux software. It is designed to be used out-of-the-box on devices requiring high reliability, allowing you to focus on your application and not on building and maintaining the operating system. Torizon OS . The platform OS - Torizon OS - is a minimal OS with a Docker runtime and libostree + Aktualizr. The main goal of this system is to allow application developers to use containers, while the maintainers of Torizon OS focus on the base system updates. TorizonCore Builder . Since the Torizon OS is meant as a binary distribution, OS customization is made easier with TorizonCore Builder, as the tool abstracts the handling of OSTree concepts from the final users. Torizon Cloud . Torizon Cloud is a hosted OTA update system that provides OS updates to Torizon OS using OSTree and Aktualizr. ", + "url": "/ostree/related-projects/#torizon-platform", + + "relUrl": "/related-projects/#torizon-platform" + },"123": { + "doc": "Anatomy of an OSTree repository", + "title": "Anatomy of an OSTree repository", + "content": ". | Core object types and data model . | Commit objects | Dirtree objects | Dirmeta objects | Content objects | Xattrs objects | . | Repository types and locations . | Refs | The summary file | . | . ", + "url": "/ostree/repo/", + + "relUrl": "/repo/" + },"124": { + "doc": "Anatomy of an OSTree repository", + "title": "Core object types and data model", + "content": "OSTree is deeply inspired by git; the core layer is a userspace content-addressed versioning filesystem. It is worth taking some time to familiarize yourself with Git Internals, as this section will assume some knowledge of how git works. Its object types are similar to git; it has commit objects and content objects. Git has “tree” objects, whereas OSTree splits them into “dirtree” and “dirmeta” objects. But unlike git, OSTree’s checksums are SHA256. And most crucially, its content objects include uid, gid, and extended attributes (but still no timestamps). Commit objects . A commit object contains metadata such as a timestamp, a log message, and most importantly, a reference to a dirtree/dirmeta pair of checksums which describe the root directory of the filesystem. Also like git, each commit in OSTree can have a parent. It is designed to store a history of your binary builds, just like git stores a history of source control. However, OSTree also makes it easy to delete data, under the assumption that you can regenerate it from source code. Dirtree objects . A dirtree contains a sorted array of (filename, checksum) pairs for content objects, and a second sorted array of (filename, dirtree checksum, dirmeta checksum), which are subdirectories. This type of object is stored as files ending with .dirtree in the objects directory. Dirmeta objects . In git, tree objects contain the metadata such as permissions for their children. But OSTree splits this into a separate object to avoid duplicating extended attribute listings. These type of objects are stored as files ending with .dirmeta in the objects directory. Content objects . Unlike the first three object types which are metadata, designed to be mmap()ed, the content object has a separate internal header and payload sections. The header contains uid, gid, mode, and symbolic link target (for symlinks), as well as extended attributes. After the header, for regular files, the content follows. These parts together form the SHA256 hash for content objects. The content type objects in this format exist only in archive OSTree repositories. Today the content part is gzip’ed and the objects are stored as files ending with .filez in the objects directory. Because the SHA256 hash is formed over the uncompressed content, these files do not match the hash they are named as. The OSTree data format intentionally does not contain timestamps. The reasoning is that data files may be downloaded at different times, and by different build systems, and so will have different timestamps but identical physical content. These files may be large, so most users would like them to be shared, both in the repository and between the repository and deployments. This could cause problems with programs that check if files are out-of-date by comparing timestamps. For Git, the logical choice is to not mess with timestamps, because unnecessary rebuilding is better than a broken tree. However, OSTree has to hardlink files to check them out, and commits are assumed to be internally consistent with no build steps needed. For this reason, OSTree acts as though all timestamps are set to time_t 0, so that comparisons will be considered up-to-date. Note that for a few releases, OSTree used 1 to fix warnings such as GNU Tar emitting “implausibly old time stamp” with 0; however, until we have a mechanism to transition cleanly to 1, for compatibilty OSTree is reverted to use zero again. Xattrs objects . In some repository modes (e.g. bare-split-xattrs), xattrs are stored on the side of the content objects they refer to. This is done via two dedicated object types, file-xattrs and file-xattrs-link. file-xattrs store xattrs data, encoded as GVariant. Each object is keyed by the checksum of the xattrs content, allowing for multiple references. file-xattrs-link are hardlinks which are associated to file objects. Each object is keyed by the same checksum of the corresponding file object. The target of the hardlink is an existing file-xattrs object. In case of reaching the limit of too many links, this object could be a plain file too. ", + "url": "/ostree/repo/#core-object-types-and-data-model", + + "relUrl": "/repo/#core-object-types-and-data-model" + },"125": { + "doc": "Anatomy of an OSTree repository", + "title": "Repository types and locations", + "content": "Also unlike git, an OSTree repository can be in one of five separate modes: bare, bare-split-xattrs, bare-user, bare-user-only, and archive. A bare repository is one where content files are just stored as regular files; it’s designed to be the source of a “hardlink farm”, where each operating system checkout is merely links into it. If you want to store files owned by e.g. root in this mode, you must run OSTree as root. The bare-split-xattrs mode is similar to the above one, but it does store xattrs as separate objects. This is meant to avoid conflicts with kernel-enforced constraints (e.g. on SELinux labels) and with other softwares that may perform ephemeral changes to xattrs (e.g. container runtimes). The bare-user mode is a later addition that is like bare in that files are unpacked, but it can (and should generally) be created as non-root. In this mode, extended metadata such as owner uid, gid, and extended attributes are stored in extended attributes under the name user.ostreemeta but not actually applied. The bare-user mode is useful for build systems that run as non-root but want to generate root-owned content, as well as non-root container systems. The bare-user-only mode is a variant to the bare-user mode. Unlike bare-user, neither ownership nor extended attributes are stored. These repos are meant to to be checked out in user mode (with the -U flag), where this information is not applied anyway. Hence this mode may lose metadata. The main advantage of bare-user-only is that repos can be stored on filesystems which do not support extended attributes, such as tmpfs. In contrast, the archive mode is designed for serving via plain HTTP. Like tar files, it can be read/written by non-root users. On an OSTree-deployed system, the “system repository” is /ostree/repo. It can be read by any uid, but only written by root. The ostree command will by default operate on the system repository; you may provide the --repo argument to override this, or set the $OSTREE_REPO environment variable. ", + "url": "/ostree/repo/#repository-types-and-locations", + + "relUrl": "/repo/#repository-types-and-locations" + },"126": { + "doc": "Anatomy of an OSTree repository", + "title": "Refs", + "content": "Like git, OSTree uses the terminology “references” (abbreviated “refs”) which are text files that name (refer to) particular commits. See the Git Documentation for information on how git uses them. Unlike git though, it doesn’t usually make sense to have a “main” branch. There is a convention for references in OSTree that looks like this: exampleos/buildmain/x86_64-runtime and exampleos/buildmain/x86_64-devel-debug. These two refs point to two different generated filesystem trees. In this example, the “runtime” tree contains just enough to run a basic system, and “devel-debug” contains all of the developer tools and debuginfo. The ostree supports a simple syntax using the caret ^ to refer to the parent of a given commit. For example, exampleos/buildmain/x86_64-runtime^ refers to the previous build, and exampleos/buildmain/x86_64-runtime^^ refers to the one before that. ", + "url": "/ostree/repo/#refs", + + "relUrl": "/repo/#refs" + },"127": { + "doc": "Anatomy of an OSTree repository", + "title": "The summary file", + "content": "A later addition to OSTree is the concept of a “summary” file, created via the ostree summary -u command. This was introduced for a few reasons. A primary use case is to be compatible with Metalink, which requires a single file with a known checksum as a target. The summary file primarily contains two mappings: . | A mapping of the refs and their checksums, equivalent to fetching the ref file individually | A list of all static deltas, along with their metadata checksums | . This currently means that it grows linearly with both items. On the other hand, using the summary file, a client can enumerate branches. Further, fetching the summary file over e.g. pinned TLS creates a strong end-to-end verification of the commit or static delta. The summary file can also be GPG signed (detached). This is currently the only way to provide GPG signatures (transitively) on deltas. If a repository administrator creates a summary file, they must thereafter run ostree summary -u to update it whenever a ref is updated or a static delta is generated. ", + "url": "/ostree/repo/#the-summary-file", + + "relUrl": "/repo/#the-summary-file" + },"128": { + "doc": "Managing content in OSTree repositories", + "title": "Managing content in OSTree repositories", + "content": ". | Mirroring repositories | Separate development vs release repositories | Promoting content along OSTree branches - “buildmain”, “smoketested” | Promoting content between OSTree repositories | Derived data - static deltas and the summary file | Pruning our build and dev repositories | Generating “scratch” deltas for efficient initial downloads | . Once you have a build system going, if you actually want client systems to retrieve the content, you will quickly feel a need for “repository management”. The command line tool ostree does cover some core functionality, but doesn’t include very high level workflows. One reason is that how content is delivered and managed has concerns very specific to the organization. For example, some operating system content vendors may want integration with a specific errata notification system when generating commits. In this section, we will describe some high level ideas and methods for managing content in OSTree repositories, mostly independent of any particular model or tool. That said, there is an associated upstream project ostree-releng-scripts which has some scripts that are intended to implement portions of this document. Another example of software which can assist in managing OSTree repositories today is the Pulp Project, which has a Pulp OSTree plugin. ", + "url": "/ostree/repository-management/", + + "relUrl": "/repository-management/" + },"129": { + "doc": "Managing content in OSTree repositories", + "title": "Mirroring repositories", + "content": "It’s very common to want to perform a full or partial mirror, in particular across organizational boundaries (e.g. an upstream OS provider, and a user that wants offline and faster access to the content). OSTree supports both full and partial mirroring of the base archive content, although not yet of static deltas. To create a mirror, first create an archive repository (you don’t need to run this as root), then add the upstream as a remote, then use pull --mirror. ostree --repo=repo init --mode=archive ostree --repo=repo remote add exampleos https://exampleos.com/ostree/repo ostree --repo=repo pull --mirror exampleos:exampleos/x86_64/standard . You can use the --depth=-1 option to retrieve all history, or a positive integer like 3 to retrieve just the last 3 commits. See also the rsync-repos script in ostree-releng-scripts. ", + "url": "/ostree/repository-management/#mirroring-repositories", + + "relUrl": "/repository-management/#mirroring-repositories" + },"130": { + "doc": "Managing content in OSTree repositories", + "title": "Separate development vs release repositories", + "content": "By default, OSTree accumulates server side history. This is actually optional in that your build system can (using the API) write a commit with no parent. But first, we’ll investigate the ramifications of server side history. Many content vendors will want to separate their internal development with what is made public to the world. Therefore, you will want (at least) two OSTree repositories, we’ll call them “dev” and “prod”. To phrase this another way, let’s say you have a continuous delivery system which is building from git and committing into your “dev” OSTree repository. This might happen tens to hundreds of times per day. That’s a substantial amount of history over time, and it’s unlikely most of your content consumers (i.e. not developers/testers) will be interested in all of it. The original vision of OSTree was to fulfill this “dev” role, and in particular the “archive” format was designed for it. Then, what you’ll want to do is promote content from “dev” to “prod”. We’ll discuss this later, but first, let’s talk about promotion inside our “dev” repository. ", + "url": "/ostree/repository-management/#separate-development-vs-release-repositories", + + "relUrl": "/repository-management/#separate-development-vs-release-repositories" + },"131": { + "doc": "Managing content in OSTree repositories", + "title": "Promoting content along OSTree branches - “buildmain”, “smoketested”", + "content": "Besides multiple repositories, OSTree also supports multiple branches inside one repository, equivalent to git’s branches. We saw in an earlier section an example branch name like exampleos/x86_64/standard. Choosing the branch name for your “prod” repository is absolutely critical as client systems will reference it. It becomes an important part of your face to the world, in the same way the “main” branch in a git repository is. But with your “dev” repository internally, it can be very useful to use OSTree’s branching concepts to represent different stages in a software delivery pipeline. Deriving from exampleos/x86_64/standard, let’s say our “dev” repository contains exampleos/x86_64/buildmain/standard. We choose the term “buildmain” to represent something that came straight from git main. It may not be tested very much. Our next step should be to hook up a testing system (Jenkins, Buildbot, etc.) to this. When a build (commit) passes some tests, we want to “promote” that commit. Let’s create a new branch called smoketested to say that some basic sanity checks pass on the complete system. This might be where human testers get involved, for example. This is a basic way to “promote” the buildmain commit that passed testing: . ostree commit -b exampleos/x86_64/smoketested/standard -s 'Passed tests' --tree=ref=aec070645fe53... Here we’re generating a new commit object (perhaps include in the commit log links to build logs, etc.), but we’re reusing the content from the buildmain commit aec070645fe53 that passed the smoketests. For a more sophisticated implementation of this model, see the do-release-tags script, which includes support for things like propagating version numbers across commit promotion. We can easily generalize this model to have an arbitrary number of stages like exampleos/x86_64/stage-1-pass/standard, exampleos/x86_64/stage-2-pass/standard, etc. depending on business requirements and logic. In this suggested model, the “stages” are increasingly expensive. The logic is that we don’t want to spend substantial time on e.g. network performance tests if something basic like a systemd unit file fails on bootup. ", + "url": "/ostree/repository-management/#promoting-content-along-ostree-branches---buildmain-smoketested", + + "relUrl": "/repository-management/#promoting-content-along-ostree-branches---buildmain-smoketested" + },"132": { + "doc": "Managing content in OSTree repositories", + "title": "Promoting content between OSTree repositories", + "content": "Now, we have our internal continuous delivery stream flowing, it’s being tested and works. We want to periodically take the latest commit on exampleos/x86_64/stage-3-pass/standard and expose it in our “prod” repository as exampleos/x86_64/standard, with a much smaller history. We’ll have other business requirements such as writing release notes (and potentially putting them in the OSTree commit message), etc. In Build Systems we saw how the pull-local command can be used to migrate content from the “build” repository (in bare-user mode) into an archive repository for serving to client systems. Following this section, we now have three repositories, let’s call them repo-build, repo-dev, and repo-prod. We’ve been pulling content from repo-build into repo-dev (which involves gzip compression among other things since it is a format change). When using pull-local to migrate content between two archive repositories, the binary content is taken unmodified. Let’s go ahead and generate a new commit in our prod repository: . checksum=$(ostree --repo=repo-dev rev-parse exampleos/x86_64/stage-3-pass/standard`) ostree --repo=repo-prod pull-local repo-dev ${checksum} ostree --repo=repo-prod commit -b exampleos/x86_64/standard \\ -s 'Release 1.2.3' --add-metadata-string=version=1.2.3 \\ --tree=ref=${checksum} . There are a few things going on here. First, we found the latest commit checksum for the “stage-3 dev”, and told pull-local to copy it, without using the branch name. We do this because we don’t want to expose the exampleos/x86_64/stage-3-pass/standard branch name in our “prod” repository. Next, we generate a new commit in prod that’s referencing the exact binary content in dev. If the “dev” and “prod” repositories are on the same Unix filesystem, (like git) OSTree will make use of hard links to avoid copying any content at all - making the process very fast. Another interesting thing to notice here is that we’re adding an version metadata string to the commit. This is an optional piece of metadata, but we are encouraging its use in the OSTree ecosystem of tools. Commands like ostree admin status show it by default. ", + "url": "/ostree/repository-management/#promoting-content-between-ostree-repositories", + + "relUrl": "/repository-management/#promoting-content-between-ostree-repositories" + },"133": { + "doc": "Managing content in OSTree repositories", + "title": "Derived data - static deltas and the summary file", + "content": "As discussed in Formats, the archive repository we use for “prod” requires one HTTP fetch per client request by default. If we’re only performing a release e.g. once a week, it’s appropriate to use “static deltas” to speed up client updates. So once we’ve used the above command to pull content from repo-dev into repo-prod, let’s generate a delta against the previous commit: . ostree --repo=repo-prod static-delta generate exampleos/x86_64/standard . We may also want to support client systems upgrading from two commits previous. ostree --repo=repo-prod static-delta generate --from=exampleos/x86_64/standard^^ --to=exampleos/x86_64/standard . Generating a full permutation of deltas across all prior versions can get expensive, and there is some support in the OSTree core for static deltas which “recurse” to a parent. This can help create a model where clients download a chain of deltas. Support for this is not fully implemented yet however. Regardless of whether or not you choose to generate static deltas, you should update the summary file: . ostree --repo=repo-prod summary -u . (Remember, the summary command cannot be run concurrently, so this should be triggered serially by other jobs). There is some more information on the design of the summary file in Repo. ", + "url": "/ostree/repository-management/#derived-data---static-deltas-and-the-summary-file", + + "relUrl": "/repository-management/#derived-data---static-deltas-and-the-summary-file" + },"134": { + "doc": "Managing content in OSTree repositories", + "title": "Pruning our build and dev repositories", + "content": "First, the OSTree author believes you should not use OSTree as a “primary content store”. The binaries in an OSTree repository should be derived from a git repository. Your build system should record proper metadata such as the configuration options used to generate the build, and you should be able to rebuild it if necessary. Art assets should be stored in a system that’s designed for that (e.g. Git LFS). Another way to say this is that five years down the line, we are unlikely to care about retaining the exact binaries from an OS build on Wednesday afternoon three years ago. We want to save space and prune our “dev” repository. ostree --repo=repo-dev prune --refs-only --keep-younger-than=\"6 months ago\" . That will truncate the history older than 6 months. Deleted commits will have “tombstone markers” added so that you know they were explicitly deleted, but all content in them (that is not referenced by a still retained commit) will be garbage collected. ", + "url": "/ostree/repository-management/#pruning-our-build-and-dev-repositories", + + "relUrl": "/repository-management/#pruning-our-build-and-dev-repositories" + },"135": { + "doc": "Managing content in OSTree repositories", + "title": "Generating “scratch” deltas for efficient initial downloads", + "content": "In general, the happy path for OSTree downloads is via static deltas. If you are in a situation where you want to download an OSTree commit from an uninitialized repo (or one with unrelated history), you can generate “scratch” (aka --empty deltas) which bundle all objects for that commit. The tradeoff here is increasing server disk space in return for many fewer client HTTP requests. For example: . $ ostree --repo=/path/to/repo static-delta generate --empty --to=exampleos/x86_64/testing-devel $ ostree --repo=/path/to/repo summary -u . After that, clients fetching that commit will prefer fetching the “scratch” delta if they don’t have the original ref. ", + "url": "/ostree/repository-management/#generating-scratch-deltas-for-efficient-initial-downloads", + + "relUrl": "/repository-management/#generating-scratch-deltas-for-efficient-initial-downloads" + },"136": { + "doc": "OSTree and /var handling", + "title": "OSTree and /var handling", + "content": ". | OSTree and /var handling . | Default commit/image /var handling | Pitfalls | Examples . | debs/RPMs which drop files into /opt (i.e. /var/opt) | Apache default content in /var/www/html | User home directories and databases | /var/lib/containers | dnf /var/lib/dnf/history.sqlite | . | Previous ostree /var and tmpfiles.d /usr/share/factory/var | . | . ", + "url": "/ostree/var/", + + "relUrl": "/var/" + },"137": { + "doc": "OSTree and /var handling", + "title": "Default commit/image /var handling", + "content": "As of OSTree 2024.3, when a commit is “deployed” (queued to boot), the initial content of /var in a commit will be placed into the “stateroot” (default var) if the stateroot var is empty. The semantics of this are intended to match that of Docker “volumes”; consider that ostree systems have the equivalent of VOLUME /var by default. It is still strongly recommended to use systemd tmpfiles.d snippets to populate directory structure and the like in /var on firstboot, because this is more resilent. Even better, use StateDirectory= for systemd units. ", + "url": "/ostree/var/#default-commitimage-var-handling", + + "relUrl": "/var/#default-commitimage-var-handling" + },"138": { + "doc": "OSTree and /var handling", + "title": "Pitfalls", + "content": "On subsequent upgrades, normally /var would not be empty anymore (as it’s typically expected that basics like /var/tmp etc. are created, if not also other local state such as /var/log etc.). Hence, no updates from the commit/container will be applied. To be clear then: . | Any files which already exist will not be updated. | Any files which are deleted in the new version will not be deleted on existing systems. | . ", + "url": "/ostree/var/#pitfalls", + + "relUrl": "/var/#pitfalls" + },"139": { + "doc": "OSTree and /var handling", + "title": "Examples", + "content": "debs/RPMs which drop files into /opt (i.e. /var/opt) . The default OSTree “strict” layout has /opt be a symlink to /var/opt. Including any packaged content that “straddles” /usr and /var (i.e. /var/opt) will over time cause drift because changes in the package will not be reflected on disk. For situations like this, it’s strongly recommended to enable either composefs.enabled = true or the root.transient = true option for ostree-prepare-root.conf and change ensure your commit/container image has /opt as a plain directory. In the former case, content in /opt will be immutable at runtime, the same as everything else in /usr. In the latter case content it will be writable but transient. There’s also a currently-experimental ../man/ostree-state-overlay@.service.xml which can manage stateful writable overlays for individual mounts. Apache default content in /var/www/html . In general, such static content would much better live in /usr - or even better, in an application container. User home directories and databases . The semantics here are likely OK for the use case of “default users”. /var/lib/containers . Pulling container images into OSTree commits like this would be a bad idea; similar problems as RPM content. dnf /var/lib/dnf/history.sqlite . For $reasons dnf has its own database for state distinct from the RPM database, which on rpm-ostree systems is in /usr/share/rpm (under the read-only bind mount, managed by OS updates). In an image/container-oriented flow, we don’t really care about this database which mainly holds things like “was this package user installed”. This data could move to /usr. ", + "url": "/ostree/var/#examples", + + "relUrl": "/var/#examples" + },"140": { + "doc": "OSTree and /var handling", + "title": "Previous ostree /var and tmpfiles.d /usr/share/factory/var", + "content": "From OSTree versions 2023.8 to v2024.3 the /usr/lib/tmpfiles.d/ostree-tmpfiles.conf file included this snippet: . # Automatically propagate all /var content from /usr/share/factory/var; # the ostree-container stack is being changed to do this, and we want to # encourage ostree use cases in general to follow this pattern. C+! /var - - - - - . Until version 0.13.2 of the ostree-ext project, content in /var in fetched container images is moved to /usr/share/factory/var, but this no longer happens when targeting ostree v2024.3. Together, this will have the semantic that on OS updates, on the next boot (early in boot), any new files/directories will be copied. For more information on this, see man tmpfiles.d. This has been reverted, and the semantics defer to the above ostree semantic. ", + "url": "/ostree/var/#previous-ostree-var-and-tmpfilesd-usrsharefactoryvar", + + "relUrl": "/var/#previous-ostree-var-and-tmpfilesd-usrsharefactoryvar" + } +} diff --git a/assets/js/vendor/lunr.min.js b/assets/js/vendor/lunr.min.js new file mode 100644 index 0000000000..46c594b808 --- /dev/null +++ b/assets/js/vendor/lunr.min.js @@ -0,0 +1,61 @@ +/** + * lunr - http://lunrjs.com - A bit like Solr, but much smaller and not as bright - 2.3.9 + * Copyright (C) 2020 Oliver Nightingale + * @license MIT + */ +/** + * ORIGINAL MIT LICENSE + * Copyright (C) 2013 by Oliver Nightingale + + Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + */ +!function(){var e,t,r,i,n,s,o,a,u,l,c,h,d,f,p,y,m,g,x,v,w,Q,k,S,E,L,b,P,T=function(e){var t=new T.Builder;return t.pipeline.add(T.trimmer,T.stopWordFilter,T.stemmer),t.searchPipeline.add(T.stemmer),e.call(t,t),t.build()};T.version="2.3.9" +/*! +* lunr.utils +* Copyright (C) 2020 Oliver Nightingale +*/,T.utils={},T.utils.warn=(e=this,function(t){e.console&&console.warn&&console.warn(t)}),T.utils.asString=function(e){return null==e?"":e.toString()},T.utils.clone=function(e){if(null==e)return e;for(var t=Object.create(null),r=Object.keys(e),i=0;i0){var u=T.utils.clone(t)||{};u.position=[o,a],u.index=n.length,n.push(new T.Token(r.slice(o,s),u))}o=s+1}}return n},T.tokenizer.separator=/[\s\-]+/ +/*! +* lunr.Pipeline +* Copyright (C) 2020 Oliver Nightingale +*/,T.Pipeline=function(){this._stack=[]},T.Pipeline.registeredFunctions=Object.create(null),T.Pipeline.registerFunction=function(e,t){t in this.registeredFunctions&&T.utils.warn("Overwriting existing registered function: "+t),e.label=t,T.Pipeline.registeredFunctions[e.label]=e},T.Pipeline.warnIfFunctionNotRegistered=function(e){e.label&&e.label in this.registeredFunctions||T.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},T.Pipeline.load=function(e){var t=new T.Pipeline;return e.forEach((function(e){var r=T.Pipeline.registeredFunctions[e];if(!r)throw new Error("Cannot load unregistered function: "+e);t.add(r)})),t},T.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach((function(e){T.Pipeline.warnIfFunctionNotRegistered(e),this._stack.push(e)}),this)},T.Pipeline.prototype.after=function(e,t){T.Pipeline.warnIfFunctionNotRegistered(t);var r=this._stack.indexOf(e);if(-1==r)throw new Error("Cannot find existingFn");r+=1,this._stack.splice(r,0,t)},T.Pipeline.prototype.before=function(e,t){T.Pipeline.warnIfFunctionNotRegistered(t);var r=this._stack.indexOf(e);if(-1==r)throw new Error("Cannot find existingFn");this._stack.splice(r,0,t)},T.Pipeline.prototype.remove=function(e){var t=this._stack.indexOf(e);-1!=t&&this._stack.splice(t,1)},T.Pipeline.prototype.run=function(e){for(var t=this._stack.length,r=0;r1&&(se&&(r=n),s!=e);)i=r-t,n=t+Math.floor(i/2),s=this.elements[2*n];return s==e||s>e?2*n:sa?l+=2:o==a&&(t+=r[u+1]*i[l+1],u+=2,l+=2);return t},T.Vector.prototype.similarity=function(e){return this.dot(e)/this.magnitude()||0},T.Vector.prototype.toArray=function(){for(var e=new Array(this.elements.length/2),t=1,r=0;t0){var s,o=n.str.charAt(0);o in n.node.edges?s=n.node.edges[o]:(s=new T.TokenSet,n.node.edges[o]=s),1==n.str.length&&(s.final=!0),i.push({node:s,editsRemaining:n.editsRemaining,str:n.str.slice(1)})}if(0!=n.editsRemaining){if("*"in n.node.edges)var a=n.node.edges["*"];else{a=new T.TokenSet;n.node.edges["*"]=a}if(0==n.str.length&&(a.final=!0),i.push({node:a,editsRemaining:n.editsRemaining-1,str:n.str}),n.str.length>1&&i.push({node:n.node,editsRemaining:n.editsRemaining-1,str:n.str.slice(1)}),1==n.str.length&&(n.node.final=!0),n.str.length>=1){if("*"in n.node.edges)var u=n.node.edges["*"];else{u=new T.TokenSet;n.node.edges["*"]=u}1==n.str.length&&(u.final=!0),i.push({node:u,editsRemaining:n.editsRemaining-1,str:n.str.slice(1)})}if(n.str.length>1){var l,c=n.str.charAt(0),h=n.str.charAt(1);h in n.node.edges?l=n.node.edges[h]:(l=new T.TokenSet,n.node.edges[h]=l),1==n.str.length&&(l.final=!0),i.push({node:l,editsRemaining:n.editsRemaining-1,str:c+n.str.slice(2)})}}}return r},T.TokenSet.fromString=function(e){for(var t=new T.TokenSet,r=t,i=0,n=e.length;i=e;t--){var r=this.uncheckedNodes[t],i=r.child.toString();i in this.minimizedNodes?r.parent.edges[r.char]=this.minimizedNodes[i]:(r.child._str=i,this.minimizedNodes[i]=r.child),this.uncheckedNodes.pop()}} +/*! +* lunr.Index +* Copyright (C) 2020 Oliver Nightingale +*/,T.Index=function(e){this.invertedIndex=e.invertedIndex,this.fieldVectors=e.fieldVectors,this.tokenSet=e.tokenSet,this.fields=e.fields,this.pipeline=e.pipeline},T.Index.prototype.search=function(e){return this.query((function(t){new T.QueryParser(e,t).parse()}))},T.Index.prototype.query=function(e){for(var t=new T.Query(this.fields),r=Object.create(null),i=Object.create(null),n=Object.create(null),s=Object.create(null),o=Object.create(null),a=0;a1?1:e},T.Builder.prototype.k1=function(e){this._k1=e},T.Builder.prototype.add=function(e,t){var r=e[this._ref],i=Object.keys(this._fields);this._documents[r]=t||{},this.documentCount+=1;for(var n=0;n=this.length)return T.QueryLexer.EOS;var e=this.str.charAt(this.pos);return this.pos+=1,e},T.QueryLexer.prototype.width=function(){return this.pos-this.start},T.QueryLexer.prototype.ignore=function(){this.start==this.pos&&(this.pos+=1),this.start=this.pos},T.QueryLexer.prototype.backup=function(){this.pos-=1},T.QueryLexer.prototype.acceptDigitRun=function(){var e,t;do{t=(e=this.next()).charCodeAt(0)}while(t>47&&t<58);e!=T.QueryLexer.EOS&&this.backup()},T.QueryLexer.prototype.more=function(){return this.pos1&&(e.backup(),e.emit(T.QueryLexer.TERM)),e.ignore(),e.more())return T.QueryLexer.lexText},T.QueryLexer.lexEditDistance=function(e){return e.ignore(),e.acceptDigitRun(),e.emit(T.QueryLexer.EDIT_DISTANCE),T.QueryLexer.lexText},T.QueryLexer.lexBoost=function(e){return e.ignore(),e.acceptDigitRun(),e.emit(T.QueryLexer.BOOST),T.QueryLexer.lexText},T.QueryLexer.lexEOS=function(e){e.width()>0&&e.emit(T.QueryLexer.TERM)},T.QueryLexer.termSeparator=T.tokenizer.separator,T.QueryLexer.lexText=function(e){for(;;){var t=e.next();if(t==T.QueryLexer.EOS)return T.QueryLexer.lexEOS;if(92!=t.charCodeAt(0)){if(":"==t)return T.QueryLexer.lexField;if("~"==t)return e.backup(),e.width()>0&&e.emit(T.QueryLexer.TERM),T.QueryLexer.lexEditDistance;if("^"==t)return e.backup(),e.width()>0&&e.emit(T.QueryLexer.TERM),T.QueryLexer.lexBoost;if("+"==t&&1===e.width())return e.emit(T.QueryLexer.PRESENCE),T.QueryLexer.lexText;if("-"==t&&1===e.width())return e.emit(T.QueryLexer.PRESENCE),T.QueryLexer.lexText;if(t.match(T.QueryLexer.termSeparator))return T.QueryLexer.lexTerm}else e.escapeCharacter()}},T.QueryParser=function(e,t){this.lexer=new T.QueryLexer(e),this.query=t,this.currentClause={},this.lexemeIdx=0},T.QueryParser.prototype.parse=function(){this.lexer.run(),this.lexemes=this.lexer.lexemes;for(var e=T.QueryParser.parseClause;e;)e=e(this);return this.query},T.QueryParser.prototype.peekLexeme=function(){return this.lexemes[this.lexemeIdx]},T.QueryParser.prototype.consumeLexeme=function(){var e=this.peekLexeme();return this.lexemeIdx+=1,e},T.QueryParser.prototype.nextClause=function(){var e=this.currentClause;this.query.clause(e),this.currentClause={}},T.QueryParser.parseClause=function(e){var t=e.peekLexeme();if(null!=t)switch(t.type){case T.QueryLexer.PRESENCE:return T.QueryParser.parsePresence;case T.QueryLexer.FIELD:return T.QueryParser.parseField;case T.QueryLexer.TERM:return T.QueryParser.parseTerm;default:var r="expected either a field or a term, found "+t.type;throw t.str.length>=1&&(r+=" with value '"+t.str+"'"),new T.QueryParseError(r,t.start,t.end)}},T.QueryParser.parsePresence=function(e){var t=e.consumeLexeme();if(null!=t){switch(t.str){case"-":e.currentClause.presence=T.Query.presence.PROHIBITED;break;case"+":e.currentClause.presence=T.Query.presence.REQUIRED;break;default:var r="unrecognised presence operator'"+t.str+"'";throw new T.QueryParseError(r,t.start,t.end)}var i=e.peekLexeme();if(null==i){r="expecting term or field, found nothing";throw new T.QueryParseError(r,t.start,t.end)}switch(i.type){case T.QueryLexer.FIELD:return T.QueryParser.parseField;case T.QueryLexer.TERM:return T.QueryParser.parseTerm;default:r="expecting term or field, found '"+i.type+"'";throw new T.QueryParseError(r,i.start,i.end)}}},T.QueryParser.parseField=function(e){var t=e.consumeLexeme();if(null!=t){if(-1==e.query.allFields.indexOf(t.str)){var r=e.query.allFields.map((function(e){return"'"+e+"'"})).join(", "),i="unrecognised field '"+t.str+"', possible fields: "+r;throw new T.QueryParseError(i,t.start,t.end)}e.currentClause.fields=[t.str];var n=e.peekLexeme();if(null==n){i="expecting term, found nothing";throw new T.QueryParseError(i,t.start,t.end)}if(n.type===T.QueryLexer.TERM)return T.QueryParser.parseTerm;i="expecting term, found '"+n.type+"'";throw new T.QueryParseError(i,n.start,n.end)}},T.QueryParser.parseTerm=function(e){var t=e.consumeLexeme();if(null!=t){e.currentClause.term=t.str.toLowerCase(),-1!=t.str.indexOf("*")&&(e.currentClause.usePipeline=!1);var r=e.peekLexeme();if(null!=r)switch(r.type){case T.QueryLexer.TERM:return e.nextClause(),T.QueryParser.parseTerm;case T.QueryLexer.FIELD:return e.nextClause(),T.QueryParser.parseField;case T.QueryLexer.EDIT_DISTANCE:return T.QueryParser.parseEditDistance;case T.QueryLexer.BOOST:return T.QueryParser.parseBoost;case T.QueryLexer.PRESENCE:return e.nextClause(),T.QueryParser.parsePresence;default:var i="Unexpected lexeme type '"+r.type+"'";throw new T.QueryParseError(i,r.start,r.end)}else e.nextClause()}},T.QueryParser.parseEditDistance=function(e){var t=e.consumeLexeme();if(null!=t){var r=parseInt(t.str,10);if(isNaN(r)){var i="edit distance must be numeric";throw new T.QueryParseError(i,t.start,t.end)}e.currentClause.editDistance=r;var n=e.peekLexeme();if(null!=n)switch(n.type){case T.QueryLexer.TERM:return e.nextClause(),T.QueryParser.parseTerm;case T.QueryLexer.FIELD:return e.nextClause(),T.QueryParser.parseField;case T.QueryLexer.EDIT_DISTANCE:return T.QueryParser.parseEditDistance;case T.QueryLexer.BOOST:return T.QueryParser.parseBoost;case T.QueryLexer.PRESENCE:return e.nextClause(),T.QueryParser.parsePresence;default:i="Unexpected lexeme type '"+n.type+"'";throw new T.QueryParseError(i,n.start,n.end)}else e.nextClause()}},T.QueryParser.parseBoost=function(e){var t=e.consumeLexeme();if(null!=t){var r=parseInt(t.str,10);if(isNaN(r)){var i="boost must be numeric";throw new T.QueryParseError(i,t.start,t.end)}e.currentClause.boost=r;var n=e.peekLexeme();if(null!=n)switch(n.type){case T.QueryLexer.TERM:return e.nextClause(),T.QueryParser.parseTerm;case T.QueryLexer.FIELD:return e.nextClause(),T.QueryParser.parseField;case T.QueryLexer.EDIT_DISTANCE:return T.QueryParser.parseEditDistance;case T.QueryLexer.BOOST:return T.QueryParser.parseBoost;case T.QueryLexer.PRESENCE:return e.nextClause(),T.QueryParser.parsePresence;default:i="Unexpected lexeme type '"+n.type+"'";throw new T.QueryParseError(i,n.start,n.end)}else e.nextClause()}},b=this,P=function(){return T},"function"==typeof define&&define.amd?define(P):"object"==typeof exports?module.exports=P():b.lunr=P()}(); diff --git a/atomic-rollbacks/index.html b/atomic-rollbacks/index.html new file mode 100644 index 0000000000..bb56fd40bc --- /dev/null +++ b/atomic-rollbacks/index.html @@ -0,0 +1,419 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Atomic Rollbacks | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Atomic Rollbacks + + +

+ + +
    +
  1. Automatic rollbacks
  2. +
  3. Manual rollbacks
  4. +
  5. Rollbacks
  6. +
  7. Alternate rollback techniques
  8. +
+ + +

+ + + Automatic rollbacks + + +

+ + +

See greenboot for information on automatic rollbacks and how to integrate +without your bootloader.

+

+ + + Manual rollbacks + + +

+ + +

Ostree writes bootloader entries that are interpreted by the bootloader. To +manually rollback, for bootloaders such as GRUB and syslinux that have an +interactive UI, it is possible to select a previous boot entry. In the case of +an Android bootloader, a slot switch may be triggererd using an AB switching +tool. This may be useful for testing purposes.

+

+ + + Rollbacks + + +

+ + +
                        +------------------------------------------------+
++------------------+    |                                                |
+|                  |    |                                                |
+|                  |    |                                                |
+|                  |    |      (ostree:0) latest     (multi-user.target) |
+|                  |    |                                                |
+| Bootloader       |--->+ root                                           |
+|                  |    |                                                |
+|                  |    |      (ostree:1) latest - 1 (multi-user.target) |
+|                  |    |                                                |
+|                  |    |                                                |
++------------------+    |                                                |
+                        +------------------------------------------------+
+
+ +

Bootloaders have multiple boot entries to choose from after upgrade. On +rollback, the bootloader will boot the “latest - 1” version, rather than the +latest version of the OS.

+

+ + + Alternate rollback techniques + + +

+ + +

Below is an alternate technique to traditional AB switching that can be used. +On rollback, an alternative boot target is used, rather than booting as +default.target.

+ +
                        +------------------------------------------------+
++------------------+    |                                                |
+|                  |    |                                                |
+|                  |    |                                                |
+|                  |    |      (ostree:0) latest     (multi-user.target) |
+|                  |    |                                                |
+| Bootloader       |--->+ root                                           |
+|                  |    |                                                |
+|                  |    |      (ostree:1) latest - 1 (rescue.target)     |
+|                  |    |                                                |
+|                  |    |                                                |
++------------------+    |                                                |
+                        +------------------------------------------------+
+
+ +

In this case, instead of rolling back to an older version, we also boot +into an alternate systemd boot target. Here we will describe how you can put +togther an alternate systemd boot target, using the built-in rescue.target as +an example.

+ +

Below is a rescue.service file, it essentially executes systemd-sulogin-shell +rescue when this service is activated.

+ +

rescue.service:

+ +
#  SPDX-License-Identifier: LGPL-2.1-or-later
+#
+#  This file is part of systemd.
+#
+#  systemd is free software; you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 2.1 of the License, or
+#  (at your option) any later version.
+
+[Unit]
+Description=Rescue Shell
+Documentation=man:sulogin(8)
+DefaultDependencies=no
+Conflicts=shutdown.target
+After=sysinit.target plymouth-start.service
+Before=shutdown.target
+
+[Service]
+Environment=HOME=/root
+WorkingDirectory=-/root
+ExecStartPre=-/usr/bin/plymouth --wait quit
+ExecStart=-/usr/lib/systemd/systemd-sulogin-shell rescue
+Type=idle
+StandardInput=tty-force
+StandardOutput=inherit
+StandardError=inherit
+KillMode=process
+IgnoreSIGPIPE=no
+SendSIGHUP=yes
+
+ +

Below is a rescue.target file, it is reached once rescue.service is complete.

+ +

rescue.target:

+ +
#  SPDX-License-Identifier: LGPL-2.1-or-later
+#
+#  This file is part of systemd.
+#
+#  systemd is free software; you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 2.1 of the License, or
+#  (at your option) any later version.
+
+[Unit]
+Description=Rescue Mode
+Documentation=man:systemd.special(7)
+Requires=sysinit.target rescue.service
+After=sysinit.target rescue.service
+AllowIsolate=yes
+
+ +

This is a simple bash script, it checks whether ostree admin status -D is +not-default and if it is, it notifies systemd to alternatively boot into +rescue.target.

+ +

In the happy path, when we have booted the latest version +ostree admin status -D would output default.

+ +

ostree-rollback-to-rescue:

+ +
#!/usr/bin/bash
+
+set -euo pipefail
+
+if [ "$(ostree admin status -D)" = "not-default" ]; then
+  exec systemctl --no-block isolate rescue.target
+fi
+
+ +

This is a systemd service file that runs ostree-rollback-to-rescue early in the +boot sequence, it is essential that this service is run early to ensure we +don’t execute a full boot sequence, hence options DefaultDependencies=no and +Before= are used.

+ +

ostree-rollback-to-rescue.service

+ +
[Unit]
+Description=OSTree rollback to rescue
+DefaultDependencies=no
+OnFailure=emergency.target
+OnFailureJobMode=replace-irreversibly
+After=initrd-root-fs.target initrd-fs.target initrd.target boot.mount
+Before=cryptsetup.target integritysetup.target remote-fs.target slices.target swap.target veritysetup.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/sbin/ostree-rollback-to-rescue
+
+[Install]
+WantedBy=sysinit.target
+
+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/atomic-upgrades/index.html b/atomic-upgrades/index.html new file mode 100644 index 0000000000..c595fca9de --- /dev/null +++ b/atomic-upgrades/index.html @@ -0,0 +1,417 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Atomic Upgrades | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Atomic Upgrades + + +

+ + +
    +
  1. You can turn off the power anytime you want…
  2. +
  3. Simple upgrades via HTTP
  4. +
  5. Upgrades via external tools (e.g. package managers)
  6. +
  7. Assembling a new deployment directory
  8. +
  9. Atomically swapping boot configuration
  10. +
  11. The bootversion
  12. +
  13. The /ostree/boot directory
  14. +
+ + +

+ + + You can turn off the power anytime you want… + + +

+ + +

OSTree is designed to implement fully atomic and safe upgrades; +more generally, atomic transitions between lists of bootable +deployments. If the system crashes or you pull the power, you +will have either the old system, or the new one.

+

+ + + Simple upgrades via HTTP + + +

+ + +

First, the most basic model OSTree supports is one where it replicates +pre-generated filesystem trees from a server over HTTP, tracking +exactly one ref, which is stored in the .origin file for the +deployment. The command ostree admin upgrade +implements this.

+ +

To begin a simple upgrade, OSTree fetches the contents of the ref from +the remote server. Suppose we’re tracking a ref named +exampleos/buildmain/x86_64-runtime. OSTree fetches the URL +http://example.com/repo/refs/heads/exampleos/buildmain/x86_64-runtime, +which contains a SHA256 checksum. This determines the tree to deploy, +and /etc will be merged from currently booted tree.

+ +

If we do not have this commit, then we perform a pull process. +At present (without static deltas), this involves quite simply just +fetching each individual object that we do not have, asynchronously. +Put in other words, we only download changed files (zlib-compressed). +Each object has its checksum validated and is stored in /ostree/repo/objects/.

+ +

Once the pull is complete, we have downloaded all the objects that we need +to perform a deployment.

+

+ + + Upgrades via external tools (e.g. package managers) + + +

+ + +

As mentioned in the introduction, OSTree is also designed to allow a +model where filesystem trees are computed on the client. It is +completely agnostic as to how those trees are generated; they could be +computed with traditional packages, packages with post-deployment +scripts on top, or built by developers directly from revision control +locally, etc.

+ +

At a practical level, most package managers today (dpkg and rpm) +operate “live” on the currently booted filesystem. The way they could +work with OSTree is to, instead, take the list of installed packages in +the currently booted tree, and compute a new filesystem from that. A +later chapter describes in more details how this could work: +Adapting Existing Systems.

+ +

For the purposes of this section, let’s assume that we have a +newly generated filesystem tree stored in the repo (which shares +storage with the existing booted tree). We can then move on to +checking it back out of the repo into a deployment.

+

+ + + Assembling a new deployment directory + + +

+ + +

Given a commit to deploy, OSTree first allocates a directory for +it. This is of the form /boot/loader/entries/ostree-$stateroot-$checksum.$serial.conf. +The $serial is normally 0, but if a +given commit is deployed more than once, it will be incremented. +This is supported because the previous deployment may have +configuration in /etc that we do not want to use or overwrite.

+ +

Now that we have a deployment directory, a 3-way merge is performed +between the (by default) currently booted deployment’s /etc, its +default configuration, and the new deployment (based on its /usr/etc).

+ +

How it works is:

+
    +
  • Files in the currently booted deployment’s /etc which were modified +from the default /usr/etc (of the same deployment) are retained.
  • +
  • Files in the currently booted deployment’s /etc which were not +modified from the default /usr/etc (of the same deployment) are +upgraded to the new defaults from the new deployment’s /usr/etc.
  • +
+ +

Roughly, this means that as soon as you modify or add a file in /etc, +this file will be propagated forever as is (though there is a +corner-case, where if your modification eventually exactly matches a +future default file, then the file will go back to following future +default updates from that point on).

+ +

You can use ostree admin config-diff to see the differences between +your booted deployment’s /etc and the OSTree defaults. A command like +diff {/usr,}/etc will additional print line-level differences.

+

+ + + Atomically swapping boot configuration + + +

+ + +

At this point, a new deployment directory has been created as a +hardlink farm; the running system is untouched, and the bootloader +configuration is untouched. We want to add this deployment to the +“deployment list”.

+ +

To support a more general case, OSTree supports atomic transitioning +between arbitrary sets of deployments, with the restriction that the +currently booted deployment must always be in the new set. In the +normal case, we have exactly one deployment, which is the booted one, +and we want to add the new deployment to the list. A more complex +command might allow creating 100 deployments as part of one atomic +transaction, so that one can set up an automated system to bisect +across them.

+

+ + + The bootversion + + +

+ + +

OSTree allows swapping between boot configurations by implementing the +“swapped directory pattern” in /boot. This means it is a symbolic +link to one of two directories /ostree/boot.[0|1]. To swap the +contents atomically, if the current version is 0, we create +/ostree/boot.1, populate it with the new contents, then atomically +swap the symbolic link. Finally, the old contents can be garbage +collected at any point.

+

+ + + The /ostree/boot directory + + +

+ + +

However, we want to optimize for the case where the set of +kernel/initramfs/devicetree sets is the same between both the old and new +deployment lists. This happens when doing an upgrade that does not +include the kernel; think of a simple translation update. OSTree +optimizes for this case because on some systems /boot may be on a +separate medium such as flash storage not optimized for significant +amounts of write traffic. Related to this, modern OSTree has support +for having /boot be a read-only mount by default - it will +automatically remount read-write just for the portion of time +necessary to update the bootloader configuration.

+ +

To implement this, OSTree also maintains the directory +/ostree/boot.$bootversion, which is a set +of symbolic links to the deployment directories. The +$bootversion here must match the version of +/boot. However, in order to allow atomic transitions of +this directory, this is also a swapped directory, +so just like /boot, it has a version of 0 or 1 appended.

+ +

Each bootloader entry has a special ostree= argument which refers to +one of these symbolic links. This is parsed at runtime in the +initramfs.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/authenticated-repos/index.html b/authenticated-repos/index.html new file mode 100644 index 0000000000..c6d4f33411 --- /dev/null +++ b/authenticated-repos/index.html @@ -0,0 +1,270 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Handling access to authenticated remote repositories | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Handling access to authenticated remote repositories + + +

+ + +
    +
  1. Using mutual TLS
  2. +
  3. Using basic authentication
  4. +
  5. Using cookies
  6. +
+ + + +

There is no default concept of an “ostree server”; ostree expects to talk to a generic webserver, so any tool and technique applicable for generic HTTP can also apply to fetching content via OSTree’s builtin HTTP client.

+

+ + + Using mutual TLS + + +

+ + +

The tls-client-cert-path and tls-client-key-path expose the underlying HTTP code for mutual TLS.

+ +

Each device can be provisioned with a secret key which grants it access to the webserver.

+

+ + + Using basic authentication + + +

+ + +

The client supports HTTP basic authentication, but this has well-known management drawbacks.

+

+ + + Using cookies + + +

+ + +

Since this pull request ostree supports adding cookies to a remote configuration. This can be used with e.g. Amazon CloudFront.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/bootloaders/index.html b/bootloaders/index.html new file mode 100644 index 0000000000..18bc6bf9bc --- /dev/null +++ b/bootloaders/index.html @@ -0,0 +1,332 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Bootloaders | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Bootloaders + + +

+ + +
    +
  1. OSTree and bootloaders
  2. +
  3. OSTree and grub
  4. +
  5. OSTree and aboot
  6. +
  7. GRUB and os-prober
  8. +
  9. Anaconda
  10. +
  11. bootupd
  12. +
+ + +

+ + + OSTree and bootloaders + + +

+ + +

The intended design of OSTree is that it just writes new files into /boot/loader/entries. There is a legacy GRUB script (shipped on Fedora as ostree-grub2) that is intended only for the cases where the system GRUB does not support the blscfg verb.

+ +

In the happy path then, the flow of an OS update is just:

+ +
    +
  • ostree writes a new set of files in /boot/loader/entries (during ostree-finalize-staged.service on system shutdown)
  • +
  • On system start, GRUB reads those files
  • +
+ +

And that’s it.

+

+ + + OSTree and grub + + +

+ + +

For historical reasons, OSTree defaults to detecting the bootloader; if some GRUB files are present then OSTree will default to executing grub2-mkconfig.

+

+ + + OSTree and aboot + + +

+ + +

The Android bootloader is another bootloader than may be used with ostree. It still uses the files in /boot/loader/entries as metadata, but the boootloader does not read these files. Android bootloaders package their kernel+initramfs+cmdline+dtb in a signed binary blob called an Android Boot Image. This binary blob then is written to either partition boot_a or boot_b depending on which slot is suitable.

+ +

Android bootloaders by design inject kargs into the cmdline, some patches may be required in the Android bootloader implementation to ensure that the firmware does not switch between system_a and system_b partitions by populating a root= karg, or that a ro karg that is incompatible with ostree is not inserted. Conversly leaving the androidboot.slot_suffix= karg injecting functionality is required but this is commonplace for any Android Bootloader that does AB updates.

+ +

We have two accompanying scripts that work with this type of environment:

+ +

aboot-update is used to generate Android Boot Images to be delivered to the client.

+ +

aboot-deploy reads what the current slot is according to the androidboot.slot_suffix= karg, writes to the alternate boot_a or boot_b slot and sets a symlink either /ostree/root.a or /ostree/root.b so that it is known which userspace directory to boot into based on the androidboot.slot_suffix= karg, on subsequent boots.

+ +
+-----------------------------+                            +---------------------------------+
+|                             |    +------------------+    |                                 |
+|  firmware appends:          |    |                  |    |                                 |
+|                             +--->+ boot_a partition +--->+                                 |
+|  androidboot.slot_suffix=_a |    |                  |    |                  /ostree/root.a |
+|                             |    +------------------+    |                                 |
+|  or                         |                            | system_a partition              |
+|                             |    +------------------+    |                                 |
+|  androidboot.slot_suffix=_b |    |                  |    |                  /ostree/root.b |
+|                             +--->+ boot_b partition +--->+                                 |
+|  to cmdline                 |    |                  |    |                                 |
+|                             |    +------------------+    |                                 |
++-----------------------------+                            +---------------------------------+
+
+

+ + + GRUB and os-prober + + +

+ + +

A specific component of GRUB that can significantly impede the reliability of OS updates is the os-prober aspect, which scans all system block devices. If one doesn’t care about dual booting, avoiding this is a good idea.

+

+ + + Anaconda + + +

+ + +

Until very recently, the Anaconda project only supported setting up the bootloader (e.g. GRUB) on its own, which requires grub2-mkconfig etc. As of recently, Anaconda now supports bootupd.

+

+ + + bootupd + + +

+ + +

As of recently, the bootupd project ships static grub configs and in this case, the sysroot.bootloader should be set to none (except on s390x). +And assuming that the system grub has the blscfg support, which it does on Fedora derivatives per above.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/buildsystem-and-repos/index.html b/buildsystem-and-repos/index.html new file mode 100644 index 0000000000..8b35992a8b --- /dev/null +++ b/buildsystem-and-repos/index.html @@ -0,0 +1,450 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Writing a buildsystem and managing repositories | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Writing a buildsystem and managing repositories + + +

+ + +
    +
  1. Build vs buy
  2. +
  3. Initializing
  4. +
  5. Writing your own OSTree buildsystem
  6. +
  7. Constructing trees from unions
  8. +
  9. Migrating content between repositories
  10. +
  11. More sophisticated repository management
  12. +
+ + + +

OSTree is not a package system. It does not directly support building +source code. Rather, it is a tool for transporting and managing +content, along with package-system independent aspects like bootloader +management for updates.

+ +

We’ll assume here that we’re planning to generate commits on a build +server, then have client systems replicate it. Doing client-side +assembly is also possible of course, but this discussion will focus +primarily on server-side concerns.

+

+ + + Build vs buy + + +

+ + +

Therefore, you need to either pick an existing tool for writing +content into an OSTree repository, or write your own. An example +tool is rpm-ostree - it +takes as input RPMs, and commits them (currently oriented for +server-side, but aiming to do client-side too).

+

+ + + Initializing + + +

+ + +

For this initial discussion, we’re assuming you have a single +archive repository:

+ +
mkdir repo
+ostree --repo=repo init --mode=archive
+
+ +

You can export this via a static webserver, and configure clients to +pull from it.

+

+ + + Writing your own OSTree buildsystem + + +

+ + +

There exist many, many systems that basically follow this pattern:

+ +
$pkg --installroot=/path/to/tmpdir install foo bar baz
+$imagesystem commit --root=/path/to/tmpdir
+
+ +

For various values of $pkg such as yum, apt-get, etc., and +values of $imagesystem could be simple tarballs, Amazon Machine +Images, ISOs, etc.

+ +

Now obviously in this document, we’re going to talk about the +situation where $imagesystem is OSTree. The general idea with +OSTree is that wherever you might store a series of tarballs for +applications or OS images, OSTree is likely going to be better. For +example, it supports GPG signatures, binary deltas, writing bootloader +configuration, etc.

+ +

OSTree does not include a package/component build system simply +because there already exist plenty of good ones - rather, it is +intended to provide an infrastructure layer.

+ +

The above mentioned rpm-ostree compose tree chooses RPM as the value +of $pkg - so binaries are built as RPMs, then committed as a whole +into an OSTree commit.

+ +

But let’s discuss building our own. If you’re just experimenting, +it’s quite easy to start with the command line. We’ll assume for this +purpose that you have a build process that outputs a directory tree - +we’ll call this tool $pkginstallroot (which could be yum +--installroot or debootstrap, etc.).

+ +

Your initial prototype is going to look like:

+ +
$pkginstallroot /path/to/tmpdir
+ostree --repo=repo commit -s 'build' -b exampleos/x86_64/standard --tree=dir=/path/to/tmpdir
+
+ +

Alternatively, if your build system can generate a tarball, you can +commit that tarball into OSTree. For example, +OpenEmbedded can output a tarball, and +one can commit it via:

+ +
ostree commit -s 'build' -b exampleos/x86_64/standard --tree=tar=myos.tar
+
+

+ + + Constructing trees from unions + + +

+ + +

The above is a very simplistic model, and you will quickly notice that +it’s slow. This is because OSTree has to re-checksum and recompress +the content each time it’s committed. (Most of the CPU time is spent +in compression which gets thrown away if the content turns out to be +already stored).

+ +

A more advanced approach is to store components in OSTree itself, then +union them, and recommit them. At this point, we recommend taking a +look at the OSTree API, and choose a programming language supported by +GObject Introspection +to write your buildsystem scripts. Python may be a good choice, or +you could choose custom C code, etc.

+ +

For the purposes of this tutorial we will use shell script, but it’s +strongly recommended to choose a real programming language for your +build system.

+ +

Let’s say that your build system produces separate artifacts (whether +those are RPMs, zip files, or whatever). These artifacts should be +the result of make install DESTDIR= or similar. Basically +equivalent to RPMs/debs.

+ +

Further, in order to make things fast, we will need a separate +bare-user repository in order to perform checkouts quickly via +hardlinks. We’ll then export content into the archive repository +for use by client systems.

+ +
mkdir build-repo
+ostree --repo=build-repo init --mode=bare-user
+
+ +

You can begin committing those as individual branches:

+ +
ostree --repo=build-repo commit -b exampleos/x86_64/bash --tree=tar=bash-4.2-bin.tar.gz
+ostree --repo=build-repo commit -b exampleos/x86_64/systemd --tree=tar=systemd-224-bin.tar.gz
+
+ +

Set things up so that whenever a package changes, you redo the +commit with the new package version - conceptually, the branch +tracks the individual package versions over time, and defaults to +“latest”. This isn’t required - one could also include the version in +the branch name, and have metadata outside to determine “latest” (or +the desired version).

+ +

Now, to construct our final tree:

+ +
rm -rf exampleos-build
+for package in bash systemd; do
+  ostree --repo=build-repo checkout -U --union exampleos/x86_64/${package} exampleos-build
+done
+# Set up a "rofiles-fuse" mount point; this ensures that any processes
+# we run for post-processing of the tree don't corrupt the hardlinks.
+mkdir -p mnt
+rofiles-fuse exampleos-build mnt
+# Now run global "triggers", generate cache files:
+ldconfig -r mnt
+  (Insert other programs here)
+fusermount -u mnt
+ostree --repo=build-repo commit -b exampleos/x86_64/standard --link-checkout-speedup exampleos-build
+
+ +

There are a number of interesting things going on here. The major +architectural change is that we’re using --link-checkout-speedup. +This is a way to tell OSTree that our checkout is made via hardlinks, +and to scan the repository in order to build up a reverse (device, +inode) -> checksum mapping.

+ +

In order for this mapping to be accurate, we needed the rofiles-fuse +to ensure that any changed files had new inodes (and hence a new +checksum).

+

+ + + Migrating content between repositories + + +

+ + +

Now that we have content in our build-repo repository (in +bare-user mode), we need to move the exampleos/x86_64/standard +branch content into the repository just named repo (in archive +mode) for export, which will involve zlib compression of new objects. +We likely want to generate static deltas after that as well.

+ +

Let’s copy the content:

+ +
ostree --repo=repo pull-local build-repo exampleos/x86_64/standard
+
+ +

Clients can now incrementally download new objects - however, this +would also be a good time to generate a delta from the previous +commit.

+ +
ostree --repo=repo static-delta generate exampleos/x86_64/standard
+
+

+ + + More sophisticated repository management + + +

+ + +

Next, see Repository Management for the +next steps in managing content in OSTree repositories.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/composefs/index.html b/composefs/index.html new file mode 100644 index 0000000000..6661bfd92d --- /dev/null +++ b/composefs/index.html @@ -0,0 +1,420 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Using composefs with OSTree | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Using composefs with OSTree + + +

+ + +
    +
  1. composefs
      +
    1. Enabling composefs (unsigned)
    2. +
    3. composefs configuration
    4. +
    5. Injecting composefs digests
    6. +
    7. Signatures
    8. +
    +
  2. +
  3. Requirements
  4. +
  5. Status
  6. +
  7. Compatiblity
  8. +
  9. Comparison with other approaches
  10. +
  11. Further references
  12. +
+ + +

+ + + composefs + + +

+ + +

The composefs project is a new +hybrid Linux stacking filesystem that provides many benefits when +used for bootable host systems, such as a strong story for integrity.

+ +

At the current time, integration of composefs and ostree is experimental. +This issue tracks the latest status.

+

+ + + Enabling composefs (unsigned) + + +

+ + +

When building a disk image or to transition an existing system, run:

+ +
ostree config --repo=/ostree/repo set ex-integrity.composefs true
+
+ +

This will ensure that any future deployments (e.g. created by ostree admin upgrade) +have a .ostree.cfs file in the deployment directory which is a mountable +composefs metadata file, with a “backing store” directory that is +shared with the current /ostree/repo/objects.

+

+ + + composefs configuration + + +

+ + +

The ostree-prepare-root binary will look for ostree/prepare-root.conf in /etc and +/usr/lib in the initramfs. Using that configuration file you can enable composefs, +and specify an Ed25519 public key to validate the booted commit.

+ +

See the manpage for ostree-prepare-root for details of how to configure it.

+

+ + + Injecting composefs digests + + +

+ + +

When generating an OSTree commit, there is a CLI switch --generate-composefs-metadata +and a corresponding C API ostree_repo_commit_add_composefs_metadata. This will +inject the composefs digest as metadata into the ostree commit under a metadata +key ostree.composefs.v0. Because an OSTree commit can be signed, this allows +covering the composefs fsverity digest with a signature.

+

+ + + Signatures + + +

+ + +

If a commit is signed with an Ed25519 private key (see ostree +--sign), and composefs.keyfile is specified in prepare-root.conf, +then the initrd will find the commit being booted in the system repo +and validate its signature against the public key. It will then ensure +that the composefs digest being booted has an fs-verity digest +matching the one in the commit. This allows a fully trusted read-only +/usr.

+ +

The exact usage of the signature is up to the user, but a common way +to use it with transient keys. This is done like this:

+
    +
  • Generate a new keypair before each build
  • +
  • Embed the public key in the initrd that is part of the commit.
  • +
  • Ensure the initrd has a prepare-root.conf with [composefs] enabled=signed, and either use keypath or inject /etc/ostree/initramfs-root-binding.key; for more see man ostree-prepare-root
  • +
  • After committing, run ostree --sign with the private key.
  • +
  • Throw away the private key.
  • +
+ +

When a transient key is used this way, that ties the initrd with the +userspace part from the commit. This means each initrd can only boot +the very same userspace it was made for. For example, if an older +version of the OS has a security flaw, you can’t boot a new fixed +(signed) initrd and have it boot the older userspace with the flaw.

+

+ + + Requirements + + +

+ + +

The current default composefs integration in ostree does not have any +requirements from the underlying kernel and filesystem other than +having the following kernel options set:

+ +
    +
  • CONFIG_OVERLAY_FS
  • +
  • CONFIG_BLK_DEV_LOOP
  • +
  • CONFIG_EROFS_FS
  • +
+ +

At the current time, there are no additional userspace runtime requirements.

+

+ + + Status + + +

+ + +

IMPORTANT The integration with composefs is experimental and subject to change. Please +try it and report issues but do not deploy to production systems yet.

+

+ + + Compatiblity + + +

+ + +

One issue that ostree users transitioning to composefs may hit is that it is no +longer possible to add new toplevel directories via the chattr -i / && mkdir /somedir && chattr -i +trick. A bit more on this in the following issues:

+ + + +

However, users who were doing things like this probably want to enable the +root.transient option; see man ostree-prepare-root which will allow +this (but also change other behaviors too).

+

+ + + Comparison with other approaches + + +

+ + +

There is also support for using IMA with ostree. In short, composefs +provides much stronger and more efficient integrity:

+ +
    +
  • composefs validates an entire filesystem tree, not just individual files
  • +
  • composefs makes files actually read-only, whereas IMA does not by default
  • +
  • composefs uses fs-verity which does on-demand verification (IMA by default does a full readahead of every file accessed, though IMA can also use fs-verity as a backend)
  • +
+

+ + + Further references + + +

+ + +
    +
  • https://github.com/containers/composefs
  • +
  • https://www.kernel.org/doc/html/next/filesystems/fsverity.html
  • +
+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/contributing-tutorial/index.html b/contributing-tutorial/index.html new file mode 100644 index 0000000000..f2df9437c1 --- /dev/null +++ b/contributing-tutorial/index.html @@ -0,0 +1,850 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +OSTree Contributing Tutorial | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + OSTree Contributing Tutorial + + +

+ + +

The following guide is about OSTree forking, building, adding a command, testing the command, and submitting the change.

+ +
    +
  1. Getting Started
  2. +
  3. Building OSTree
      +
    1. Install Build Dependencies
    2. +
    3. OSTree Build Commands
        +
      1. Notes
      2. +
      3. Tip
      4. +
      +
    4. +
    +
  4. +
  5. Testing a Build
      +
    1. Testing in a Container
    2. +
    3. Testing in a Virtual Machine
    4. +
    +
  6. +
  7. Tutorial: Adding a basic builtin command to ostree
      +
    1. Modifying OSTree
    2. +
    3. Adding a new API function to libostree
    4. +
    5. OSTree Tests
    6. +
    7. Submitting a Patch
    8. +
    9. Returning Workflow
    10. +
    +
  8. +
+ + +

+ + + Getting Started + + +

+ + +

Fork https://github.com/ostreedev/ostree, then run the following commands.

+ +
$ git clone https://github.com/<username>/ostree && cd ostree
+$ git remote add upstream https://github.com/ostreedev/ostree
+$ git checkout main
+$ git fetch upstream && git branch --set-upstream-to=upstream/main main
+
+

Make a branch from main for your patch.

+ +
$ git checkout -b <name-of-branch>
+$ git branch --set-upstream-to=upstream/main <name-of-branch>
+
+

+ + + Building OSTree + + +

+ +

+ + + Install Build Dependencies + + +

+ + +

Execute one of the following group commands as superuser depending on your machine’s package manager.

+ +

For Fedora:

+ +
$ dnf install @buildsys-build dnf-plugins-core && \
+dnf builddep ostree
+
+ +

For CentOS:

+ +
$ yum install yum-utils dnf-plugins-core && \
+yum-builddep ostree
+
+ +

For Debian based distros:

+ +
$ apt-get update && \
+apt-get install build-essential && \
+apt-get build-dep ostree
+
+ +

build.sh will have a list of packages needed to build ostree.

+

+ + + OSTree Build Commands + + +

+ + +

These are the basic commands to build OSTree. Depending on the OS that OSTree will be built for, the flags or options for ./autogen.sh and ./configure will vary.

+ +

See ostree-build.sh in this tutorial below for specific commands to building OSTree for Fedora 28 and Fedora 28 Atomic Host.

+ +
# optional: autogen.sh will run this if necessary
+git submodule update --init
+
+env NOCONFIGURE=1 ./autogen.sh
+
+# run ./configure if makefile does not exist
+./configure
+
+make
+make install DESTDIR=/path/to/install/binary
+
+

+ + + Notes + + +

+ + +

Running git submodule update --init is optional since autogen.sh will check to see if one of the submodule files for example from libglnx/ or from bsdiff/ exists.

+ +

Additionally, autogen.sh will check to see if the environment variable NOCONFIGURE is set. To run ./configure manually, run autogen in a modified environment as such, env NOCONFIGURE=1 ./autogen.sh.

+ +

Otherwise, leave NOCONFIGURE empty and autogen.sh will run ./configure as part of the autogen.sh command when it executes.

+ +

For more information on --prefix see Variables for Installation Directories.

+ +

make install will generate files for /bin and /lib. If DESTDIR is unspecified then OSTree will be installed in the default directory i.e. /usr/local/bin and its static libraries in /usr/local/lib. Note that the /usr/local portion of the path can be changed using the --prefix option for ./configure.

+ +

See this GNU guide on DESTDIR Staged Installs for more information.

+

+ + + Tip + + +

+ + +

Make allows parallel execution of recipes. Use make -j<N> to speed up the build. <N> is typically $((2 * $(nproc))) for optimal performance, where nproc is the number of processing units (CPU cores) available.

+ +

See page 106 of the GNU Make Manual for more information about the --jobs or -j option.

+

+ + + Testing a Build + + +

+ + +

It is best practice to build software (definitely including ostree) in a container or virtual machine first.

+

+ + + Testing in a Container + + +

+ + +

There are a variety of container engines available and many distributions have pre-packaged versions of e.g. Podman and Docker.

+ +

If you choose to use Docker upstream, you may want to follow this post-installation guide for Docker. This will allow you to run Docker as a non-root user on a Linux based host machine.

+ +

You will need to have pushed a remote git branch $REMOTE_BRANCH (see ostree-git.sh below) in order to pull your changes into a container.

+ +

The example below uses Docker to manage containers. Save the contents of this Dockerfile somewhere on your machine:

+ +
# this pulls the fedora 28 image
+FROM registry.fedoraproject.org/fedora:28
+
+# install ostree dependencies
+RUN dnf update -y && \
+    dnf -y install @buildsys-build dnf-plugins-core  && \
+    dnf -y builddep ostree  && \
+    dnf clean all
+
+# clone ostree and update main branch
+COPY ostree-git.sh /
+RUN ../ostree-git.sh
+
+# builds ostree + any additional commands
+COPY ostree-build.sh /
+
+# entry into the container will start at this directory
+WORKDIR /ostree
+
+# run the following as `/bin/sh -c`
+# or enter the container to execute ./ostree-build.sh
+RUN ../ostree-build.sh
+
+
+ +

Save the following bash scripts in the same directory as the Dockerfile. Then change the mode bit of these files so that they are executable, by running chmod +x ostree-git.sh ostree-build.sh

+ +
#!/bin/bash
+
+# ostree-git.sh
+# Clone ostree and update main branch
+
+set -euo pipefail
+
+# Set $USERNAME to your GitHub username here.
+USERNAME=""
+
+# clone your fork of the OSTree repo, this will be in the "/" directory
+git clone https://github.com/$USERNAME/ostree.git
+cd ostree
+
+# Add upstream as remote and update main branch
+git checkout main  
+git remote add upstream https://github.com/ostreedev/ostree.git
+git pull --rebase upstream main
+
+ +
#!/bin/bash
+
+# ostree-build.sh
+# Build and test OSTree
+
+set -euo pipefail
+
+# $REMOTE_BRANCH is the name of the remote branch in your
+# repository that contains changes (e.g. my-patch).
+REMOTE_BRANCH=""
+
+# fetch updates from origin
+# origin url should be your forked ostree repository
+git fetch origin
+
+# go to branch with changes
+# if this branch already exists then checkout that branch
+exit_code="$(git checkout --track origin/$REMOTE_BRANCH; echo $?)"
+if [[ "$exit_code" == 1 ]]
+then
+    echo "This branch:" $REMOTE_BRANCH "is not a remote branch."
+    exit
+fi
+
+# make sure branch with changes is up-to-date
+git pull origin $REMOTE_BRANCH
+
+# build OSTree commands for Fedora 28 and Fedora 28 Atomic Host
+./autogen.sh --prefix=/usr --libdir=/usr/lib64 --sysconfdir=/etc
+./configure --prefix=/usr
+make -j$((2 * $(nproc)))
+make install
+
+# any additional commands go here
+
+ +

Build the container

+ +

Run docker build in the same directory of the Dockerfile like so:

+ +
$ docker build -t ostree-fedora-test .
+
+ +

When this build is done, the -t option tags the image as ostree-fedora-test.

+ +

Note: Do not forget the dot . at the end of the above command which specifies the location of the Dockerfile.

+ +

You will see ostree-fedora-test listed when running docker images:

+ +
REPOSITORY                                 TAG                 IMAGE ID            CREATED             SIZE
+ostree-fedora-test                         latest              817c04cc3656        1 day ago          978MB
+
+ +

Entering the Container

+ +

To start the ostree-fedora-test container, run:

+ +
$ docker run -it --rm --entrypoint /bin/sh --name ostree-testing ostree-fedora-test
+
+ +

Note:

+ +

--rm option tells Docker to automatically clean up the container and remove the file system when the container exits. Otherwise remove it manually by running docker rm <container name>.

+ +

The state of the container will not be saved when the shell prompt exits. Best practice is modify the Dockerfile to modify the image.

+ +

Testing in a Container Workflow

+ +
    +
  1. Edit the changes to OSTree on your local machine.
  2. +
  3. git add to stage the changed files, git commit and then git push origin <local-branch>:<remote-branch>.
  4. +
  5. +

    Testing on a new container vs. Testing on an existing container:

    + +

    If the ostree-testing container was newly built right after your changes have been committed, then the container’s build of ostree should contain your changes.

    + +

    Else: Within the ostree-testing container, run ../ostree-build.sh in the ostree directory. This will pull in changes from your branch and create a new ostree build.

    +
  6. +
  7. +

    make install will install OSTree in the default location i.e. /usr/..in a Fedora 28 container.

    +
  8. +
  9. Test ostree.
  10. +
+

+ + + Testing in a Virtual Machine + + +

+ + +

To create a Fedora 28 Atomic Host Vagrant VM, run the following commands:

+ +
$ mkdir atomic && cd atomic
+$ vagrant init fedora/28-atomic-host && vagrant up
+
+ +

An option is to use rsync to transfer ostree files to a Vagrant VM.

+ +

To find the IP address of a Vagrant VM, run vagrant ssh-config in the same directory as the Vagrantfile.

+ +

Steps to rsync files to test an ostree build:

+ +
    +
  1. +

    Copy the contents of your public ssh key on your host machine e.g. id_rsa.pub to /home/vagrant/.ssh/authorized_keys on the VM.

    +
  2. +
  3. +

    Run sudo su, followed by ssh localhost then press Ctrl+c to exit from the decision prompt. This will create the .ssh directory with the right permissions.

    +
  4. +
  5. +

    Using Vagrant as the user, run sudo cp ~/.ssh/authorized_keys /root/.ssh/. So that user root has the the same login credentials.

    +
  6. +
  7. +

    To override the Read-only file system warning, run sudo ostree admin unlock.

    +
  8. +
  9. +

    <ostree-install-dir> will serve as the local install location for ostree and the path to this directory should be absolute when specified in DESTDIR.

    +
  10. +
  11. +

    Set rsync to sync changes in /etc and /usr from <ostree-install-dir>/ on the host to the VM:

    + +
     $ rsync -av <ostree-install-dir>/etc/ root@<ip-address>:/etc
    + $ rsync -av <ostree-install-dir>/usr/ root@<ip-address>:/usr
    +
    + +

    Using option -n will execute the commands as a trial, which is helpful to list the files that will be synced.

    +
  12. +
  13. +

    Run the commands in step 6 each time a new ostree build is executed to update the change. Running ls -lt in the directory where the changed file is expected, is a simple way to check when a particular file was last modified. Proceed to the test changes ostree with the most recent changes.

    +
  14. +
+

+ + + Tutorial: Adding a basic builtin command to ostree + + +

+ +

+ + + Modifying OSTree + + +

+ + +

This will add a command which prints Hello OSTree! when ostree hello-ostree is entered.

+ +
    +
  1. +

    Create a file in src/ostree named ot-builtin-hello-ostree.c. Code that lives in here belongs to OSTree, and uses functionality from libostree.

    +
  2. +
  3. +

    Add the following to ot-builtin-hello-ostree.c:

    + +
     #include "config.h"
    +
    + #include "ot-main.h"
    + #include "ot-builtins.h"
    + #include "ostree.h"
    + #include "otutil.h"
    +
    + // Structure for options such as ostree hello-ostree --option.
    + static GOptionEntry options[] = {
    +   { NULL },
    + };
    +
    + gboolean
    + ostree_builtin_hello_ostree (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
    + {
    +   g_autoptr(OstreeRepo) repo = NULL;
    +
    +   // Creates new command context, ready to be parsed.
    +   // Input to g_option_context_new shows when running ostree <command> --help
    +   g_autoptr(GOptionContext) context = g_option_context_new ("");
    +
    +   // Parses the command context according to the ostree CLI.
    +   if (!ostree_option_context_parse (context, options, &argc, &argv, invocation, &repo, cancellable, error))
    +     return FALSE;
    +
    +   g_print("Hello OSTree!\n");
    +
    +   return TRUE;
    + }
    +
    + +

    This defines the functionality for hello-ostree. Now we have to make sure the CLI can refer to the execution function, and that autotools knows to build this file. + Note: libostree codebase supports C99 features.

    +
  4. +
  5. +

    Add the following in src/ostree/main.c:

    + +
     { "hello-ostree",               // The name of the command
    +   OSTREE_BUILTIN_FLAG_NO_REPO,  // Flag not to require the `--repo` argument, see "ot-main.h"
    +   ostree_builtin_hello_ostree,  // Execution function for the command
    +   "Print hello message" },      // Short description to appear when `ostree hello-ostree --help` is entered
    +
    +
  6. +
  7. +

    Add a macro for the function declaration of ostree_builtin_hello_ostree, in ot-builtins.h:

    + +
     BUILTINPROTO(hello_ostree);
    +
    + +

    This makes the function definition visible to the CLI.

    +
  8. +
  9. +

    Configure automake to include ot-builtin-hello-ostree.c in the build, by adding an entry in Makefile-ostree.am under ostree_SOURCES:

    + +
     src/ostree/ot-builtin-hello-ostree.c \
    +
    +
  10. +
  11. +

    Rebuild ostree:

    + +
     $ make && make install DESTDIR=/path/to/install/the/content
    +
    +
  12. +
  13. +

    Execute the new ostree binary, from where you installed it:

    + +
     $ ostree hello-ostree
    + Hello OSTree!
    +
    +
  14. +
+

+ + + Adding a new API function to libostree + + +

+ + +

This will add a new API function ostree_kernel_args_foo() in src/libostree/ostree-kernel-args.c.

+ +
    +
  1. +

    Add the following to src/libostree/ostree-kernel-args.h: + _OSTREE_PUBLIC + gboolean ostree_kernel_args_foo (const char *arg, GCancellable *cancellable, GError **error);

    +
  2. +
  3. +

    Add the following to ostree-kernel-args.c: + /** + * ostree_kernel_args_foo: + * @arg: Description of the arg + * + * Description of the function + * + * Since: $NEWVERSION //The new libostree version, for example 2022.5 + **/ + gboolean + ostree_kernel_args_foo (const char *arg, GCancellable *cancellable, GError **error) + { + //Add code here + }

    +
  4. +
  5. +

    Add the following to src/libostree/libostree-devel.sym: + LIBOSTREE_$NEWVERSION { // The new libostree version + global: + ostree_kernel_args_foo; // Function name + } LIBOSTREE_$LASTSTABLE; // The last stable libostree version

    +
  6. +
  7. +

    Add the following to Makefile-libostree.am: + if BUILDOPT_IS_DEVEL_BUILD + symbol_files += $(top_srcdir)/src/libostree/libostree-devel.sym + endif

    +
  8. +
  9. +

    Add function name ostree_kernel_args_foo to apidoc/ostree-sections.txt under <FILE>ostree-kernel-args</FILE>.

    +
  10. +
  11. +

    Call function ostree_kernel_args_foo() in your code.

    +
  12. +
+

+ + + OSTree Tests + + +

+ + +

Tests for OSTree are done by shell scripting, by running OSTree commands and examining output. These steps will go through adding a test for hello-ostree.

+ +
    +
  1. +

    Create a file in tests called test-hello-ostree.sh.

    +
  2. +
  3. +

    Add the following to test-hello-ostree.sh:

    + +
     set -euo pipefail           # Ensure the test will not silently fail
    +
    + . $(dirname $0)/libtest.sh  # Make libtest.sh functions available
    +
    + echo "1..1"                 # Declare which test is being run out of how many
    +
    + pushd ${test_tmpdir}
    +
    + ${CMD_PREFIX} ostree hello-ostree > hello-output.txt
    + assert_file_has_content hello-output.txt "Hello OSTree!"
    +
    + popd
    +
    + echo "ok hello ostree"      # Indicate test success
    +
    + +

    Many tests require a fake repository setting up (as most OSTree commands require --repo to be specified). See test-pull-depth.sh for an example of this setup.

    +
  4. +
  5. +

    Configure automake to include test-hello-ostree.sh in the build, by adding an entry in Makefile-tests.am under _installed_or_uninstalled_test_scripts:

    + +
     tests/test-hello-ostree.sh \
    +
    +
  6. +
  7. +

    Make sure test-hello-ostree.sh has executable permissions!

    + +
     $ chmod +x tests/test-hello-ostree.sh
    +
    +
  8. +
  9. +

    Run the test:

    + +
     $ make check TESTS="tests/test-hello-ostree.sh"
    +
    + +

    Multiple tests can be specified: make check TESTS="test1 test2 ...". To run all tests, use make check.

    + +

    Hopefully, the test passes! The following will be printed:

    + +
     PASS: tests/test-hello-ostree.sh 1 hello ostree
    + ============================================================================
    + Testsuite summary for libostree 2018.8
    + ============================================================================
    + # TOTAL: 1
    + # PASS:  1
    + # SKIP:  0
    + # XFAIL: 0
    + # FAIL:  0
    + # XPASS: 0
    + # ERROR: 0
    + ============================================================================
    +
    +
  10. +
+

+ + + Submitting a Patch + + +

+ + +

After you have committed your changes and tested, you are ready to submit your patch!

+ +

You should make sure your commits are placed on top of the latest changes from upstream/main:

+ +
$ git pull --rebase upstream main
+
+ +

To submit your patch, open a pull request from your forked repository. Most often, you’ll be merging into ostree:main from <username>:<branch name>.

+ +

If some of your changes are complete and you would like feedback, you may also open a pull request that has WIP (Work In Progress) in the title.

+ +

Before a pull request is considered merge ready, your commit messages should fall within the specified guideline. See Commit message style.

+ +

See CONTRIBUTING.md for information on squashing commits, and alternative options to submit patches.

+

+ + + Returning Workflow + + +

+ + +

When returning to work on a patch, it is recommended to update your fork with the latest changes in the upstream main branch.

+ +

If creating a new branch:

+ +
$ git checkout main
+$ git pull upstream main
+$ git checkout -b <name-of-patch>
+
+ +

If continuing on a branch already created:

+ +
$ git checkout <name-of-patch>
+$ git pull --rebase upstream main
+
+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/deployment/index.html b/deployment/index.html new file mode 100644 index 0000000000..36b24d39fd --- /dev/null +++ b/deployment/index.html @@ -0,0 +1,387 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Deployments | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Deployments + + +

+ + +
    +
  1. Overview
      +
    1. “stateroot” (AKA “osname”): Group of deployments that share /var
    2. +
    3. Contents of a deployment
    4. +
    5. Staged deployments
    6. +
    7. The system /boot
    8. +
    +
  2. +
+ + +

+ + + Overview + + +

+ + +

Built on top of the OSTree versioning filesystem core is a layer +that knows how to deploy, parallel install, and manage Unix-like +operating systems (accessible via ostree admin). The core content of these operating systems +are treated as read-only, but they transparently share storage.

+ +

A deployment is physically located at a path of the form +/ostree/deploy/$stateroot/deploy/$checksum. +OSTree is designed to boot directly into exactly one deployment +at a time; each deployment is intended to be a target for +chroot() or equivalent.

+

+ + + “stateroot” (AKA “osname”): Group of deployments that share /var + + +

+ + +

Each deployment is grouped in exactly one “stateroot” (also known as an “osname”); +the former term is preferred.

+ +

From above, you can see that a stateroot is physically represented in the +/ostree/deploy/$stateroot directory. For example, OSTree can allow parallel +installing Debian in /ostree/deploy/debian and Red Hat Enterprise Linux in +/ostree/deploy/rhel (subject to operating system support, present released +versions of these operating systems may not support this).

+ +

Each stateroot has exactly one copy of the traditional Unix /var, +stored physically in /ostree/deploy/$stateroot/var. OSTree provides +support tools for systemd to create a Linux bind mount that ensures +the booted deployment sees the shared copy of /var.

+ +

OSTree does not touch the contents of /var. Operating system +components such as daemon services are required to create any +directories they require there at runtime +(e.g. /var/cache/$daemonname), and to manage upgrading data formats +inside those directories.

+

+ + + Contents of a deployment + + +

+ + +

A deployment begins with a specific commit (represented as a +SHA256 hash) in the OSTree repository in /ostree/repo. This commit refers +to a filesystem tree that represents the underlying basis of a +deployment. For short, we will call this the “tree”, to +distinguish it from the concept of a deployment.

+ +

First, the tree must include a kernel (and optionally an initramfs). The +current standard locations for these are /usr/lib/modules/$kver/vmlinuz and +/usr/lib/modules/$kver/initramfs.img. The “boot checksum” will be computed +automatically. This follows the current Fedora kernel layout, and is +the current recommended path. However, older versions of libostree don’t +support this; you may need to also put kernels in the previous (legacy) +paths, which are vmlinuz(-.*)?-$checksum in either /boot or /usr/lib/ostree-boot. +The checksum should be a SHA256 hash of the kernel contents; it must be +pre-computed before storing the kernel in the repository. Optionally, +the directory can also contain an initramfs, stored as +initramfs(-.*)?-$checksum and/or a device tree, stored as +devicetree(-.*)?-$checksum. If an initramfs or devicetree exist, +the checksum must include all of the kernel, initramfs and devicetree contents. +OSTree will use this to determine which kernels are shared. The rationale for +this is to avoid computing checksums on the client by default.

+ +

The deployment should not have a traditional UNIX /etc; instead, it +should include /usr/etc. This is the “default configuration”. When +OSTree creates a deployment, it performs a 3-way merge using the +old default configuration, the active system’s /etc, and the new +default configuration. In the final filesystem tree for a deployment +then, /etc is a regular writable directory.

+ +

Besides the exceptions of /var and /etc then, the rest of the +contents of the tree are checked out as hard links into the +repository. It’s strongly recommended that operating systems ship all +of their content in /usr, but this is not a hard requirement.

+ +

Finally, a deployment may have a .origin file, stored next to its +directory. This file tells ostree admin upgrade how to upgrade it. +At the moment, OSTree only supports upgrading a single refspec. +However, in the future OSTree may support a syntax for composing +layers of trees, for example.

+

+ + + Staged deployments + + +

+ + +

As mentioned above, when OSTree creates a new deployment, a 3-way merge is done +to update its /etc. Depending on the nature of the system, this can cause an +issue: if a user or program modifies the booted /etc after the pending +deployment is created but before rebooting, those modifications will be lost. +OSTree does not do a second /etc merge on reboot.

+ +

To counter this, OSTree supports staged deployments. In this flow, deployments +are created using e.g. ostree admin upgrade --stage on the CLI. The new +deployment is still created when the command is invoked, but the 3-way /etc +merge is delayed until the system is rebooted or shut down. Additionally, +updating the bootloader is also delayed. This is done by the +ostree-finalize-staged.service systemd unit.

+ +

The main disadvantage of this approach is that rebooting can take longer and the +failure mode can be confusing (the machine will reboot into the same +deployment). In systems where the workload is well-understood and not subject to +the /etc issue above, it may be better to not stage deployments.

+

+ + + The system /boot + + +

+ + +

While OSTree parallel installs deployments cleanly inside the +/ostree directory, ultimately it has to control the system’s /boot +directory. The way this works is via the +Boot Loader Specification, +which is a standard for bootloader-independent drop-in configuration +files.

+ +

When a tree is deployed, it will have a configuration file generated +of the form +/boot/loader/entries/ostree-$stateroot-$checksum.$serial.conf. This +configuration file will include a special ostree= kernel argument +that allows the initramfs to find (and chroot() into) the specified +deployment.

+ +

At present, not all bootloaders implement the BootLoaderSpec, so +OSTree contains code for some of these to regenerate native config +files (such as /boot/syslinux/syslinux.conf) based on the entries.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/formats/index.html b/formats/index.html new file mode 100644 index 0000000000..35f610eccc --- /dev/null +++ b/formats/index.html @@ -0,0 +1,508 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +OSTree data formats | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + OSTree data formats + + +

+ + +
    +
  1. On the topic of “smart servers”
  2. +
  3. The archive format
  4. +
  5. archive efficiency
  6. +
  7. Aside: bare formats
  8. +
  9. Static deltas
  10. +
  11. Static delta repository layout
  12. +
  13. Static delta internal structure
      +
    1. The delta superblock
    2. +
    +
  14. +
  15. A delta part
  16. +
  17. Fallback objects
  18. +
+ + +

+ + + On the topic of “smart servers” + + +

+ + +

One really crucial difference between OSTree and git is that git has a +“smart server”. Even when fetching over https://, it isn’t just a +static webserver, but one that e.g. dynamically computes and +compresses pack files for each client.

+ +

In contrast, the author of OSTree feels that for operating system +updates, many deployments will want to use simple static webservers, +the same target most package systems were designed to use. The +primary advantages are security and compute efficiency. Services like +Amazon S3 and CDNs are a canonical target, as well as a stock static +nginx server.

+

+ + + The archive format + + +

+ + +

In the repo section, the concept of objects was introduced, +where file/content objects are checksummed and managed individually. +(Unlike a package system, which operates on compressed aggregates).

+ +

The archive format simply gzip-compresses each content object. +Metadata objects are stored uncompressed. This means that it’s easy +to serve via static HTTP. Note: the repo config file still uses the +historical term archive-z2 as mode. But this essentially indicates +the modern archive format.

+ +

When you commit new content, you will see new .filez files appearing +in objects/.

+

+ + + archive efficiency + + +

+ + +

The advantages of archive:

+ +
    +
  • It’s easy to understand and implement
  • +
  • Can be served directly over plain HTTP by a static webserver
  • +
  • Clients can download/unpack updates incrementally
  • +
  • Space efficient on the server
  • +
+ +

The biggest disadvantage of this format is that for a client to +perform an update, one HTTP request per changed file is required. In +some scenarios, this actually isn’t bad at all, particularly with +techniques to reduce HTTP overhead, such as +HTTP/2.

+ +

In order to make this format work well, you should design your content +such that large data that changes infrequently (e.g. graphic images) +are stored separately from small frequently changing data (application +code).

+ +

Other disadvantages of archive:

+ +
    +
  • It’s quite bad when clients are performing an initial pull (without HTTP/2),
  • +
  • One doesn’t know the total size (compressed or uncompressed) of content +before downloading everything
  • +
+

+ + + Aside: bare formats + + +

+ + +

The most common operation is to pull from a remote archive repository +into a local one. This latter is not compressed on disk. In other +words, pulling to a local repository is similar to unpacking (but not +installing) the content of an RPM/deb package.

+ +

The bare repository format is the simplest one. In this mode regular files +are directly stored to disk, and all metadata (e.g. uid/gid and xattrs) is +reflected to the filesystem. +It allows further direct access to content and metadata, but it may require +elevated privileges when writing objects to the repository.

+ +

The bare-user format is a bit special in that the uid/gid and xattrs +from the content are ignored. This is primarily useful if you want to +have the same OSTree-managed content that can be run on a host system +or an unprivileged container.

+ +

Similarly, the bare-split-xattrs format is a special mode where xattrs +are stored as separate repository objects, and not directly reflected to +the filesystem. +This is primarily useful when transporting xattrs through lossy environments +(e.g. tar streams and containerized environments). It also allows carrying +security-sensitive xattrs (e.g. SELinux labels) out-of-band without involving +OS filesystem logic.

+

+ + + Static deltas + + +

+ + +

OSTree itself was originally focused on a continuous delivery model, where +client systems are expected to update regularly. However, many OS vendors +would like to supply content that’s updated e.g. once a month or less often.

+ +

For this model, we can do a lot better to support batched updates than +a basic archive repo. However, we still want to preserve the +model of “static webserver only”. Given this, OSTree has gained the +concept of a “static delta”.

+ +

These deltas are targeted to be a delta between two specific commit +objects, including “bsdiff” and “rsync-style” deltas within a content +object. Static deltas also support from NULL, where the client can +more efficiently download a commit object from scratch - this is +mostly useful when using OSTree for containers, rather than OS images. +For OS images, one tends to download an installer ISO or qcow2 image +which is a single file that contains the tree data already.

+ +

Effectively, we’re spending server-side storage (and one-time compute +cost), and gaining efficiency in client network bandwidth.

+

+ + + Static delta repository layout + + +

+ + +

Since static deltas may not exist, the client first needs to attempt +to locate one. Suppose a client wants to retrieve commit ${new} +while currently running ${current}.

+ +

In order to save space, these two commits are “modified base64” - the +/ character is replaced with _.

+ +

Like the commit objects, a “prefix directory” is used to make +management easier for filesystem tools.

+ +

A delta is named $(mbase64 $from)-$(mbase64 $to), for example +GpTyZaVut2jXFPWnO4LJiKEdRTvOw_mFUCtIKW1NIX0-L8f+VVDkEBKNc1Ncd+mDUrSVR4EyybQGCkuKtkDnTwk, +which in SHA256 format is +1a94f265a56eb768d714f5a73b82c988a11d453bcec3f985502b48296d4d217d-2fc7fe5550e410128d73535c77e98352b495478132c9b4060a4b8ab640e74f09.

+ +

Finally, the actual content can be found in +deltas/$fromprefix/$fromsuffix-$to.

+

+ + + Static delta internal structure + + +

+ + +

A delta is itself a directory. Inside, there is a file called +superblock which contains metadata. The rest of the files will be +integers bearing packs of content.

+ +

The file format of static deltas should be currently considered an +OSTree implementation detail. Obviously, nothing stops one from +writing code which is compatible with OSTree today. However, we would +like the flexibility to expand and change things, and having multiple +codebases makes that more problematic. Please contact the authors +with any requests.

+ +

That said, one critical thing to understand about the design is that +delta payloads are a bit more like “restricted programs” than they are +raw data. There’s a “compilation” phase which generates output that +the client executes.

+ +

This “updates as code” model allows for multiple content generation +strategies. The design of this was inspired by that of Chromium: +ChromiumOS Autoupdate.

+

+ + + The delta superblock + + +

+ + +

The superblock contains:

+ +
    +
  • arbitrary metadata
  • +
  • delta generation timestamp
  • +
  • the new commit object
  • +
  • An array of recursive deltas to apply
  • +
  • An array of per-part metadata, including total object sizes (compressed and uncompressed),
  • +
  • An array of fallback objects
  • +
+ +

Let’s define a delta part, then return to discuss details:

+

+ + + A delta part + + +

+ + +

A delta part is a combination of a raw blob of data, plus a very +restricted bytecode that operates on it. Say for example two files +happen to share a common section. It’s possible for the delta +compilation to include that section once in the delta data blob, then +generate instructions to write out that blob twice when generating +both objects.

+ +

Realistically though, it’s very common for most of a delta to just be +“stream of new objects” - if one considers it, it doesn’t make sense +to have too much duplication inside operating system content at this +level.

+ +

So then, what’s more interesting is that OSTree static deltas support +a per-file delta algorithm called +bsdiff that most notably works +well on executable code.

+ +

The current delta compiler scans for files with matching basenames in +each commit that have a similar size, and attempts a bsdiff between +them. (It would make sense later to have a build system provide a +hint for this - for example, files within a same package).

+ +

A generated bsdiff is included in the payload blob, and applying it is +an instruction.

+

+ + + Fallback objects + + +

+ + +

It’s possible for there to be large-ish files which might be resistant +to bsdiff. A good example is that it’s common for operating systems +to use an “initramfs”, which is itself a compressed filesystem. This +“internal compression” defeats bsdiff analysis.

+ +

For these types of objects, the delta superblock contains an array of +“fallback objects”. These objects aren’t included in the delta +parts - the client simply fetches them from the underlying .filez +object.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/ima/index.html b/ima/index.html new file mode 100644 index 0000000000..28619e0395 --- /dev/null +++ b/ima/index.html @@ -0,0 +1,397 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Using Linux IMA with OSTree | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Using Linux IMA with OSTree + + +

+ + +
    +
  1. Linux IMA
  2. +
  3. IMA signatures and OSTree checksum
  4. +
  5. Signing
      +
    1. Generating a key
    2. +
    3. Signing a commit
    4. +
    5. Applying a policy
    6. +
    7. Linux EVM
    8. +
    +
  6. +
  7. Further references
  8. +
+ + +

+ + + Linux IMA + + +

+ + +

The Linux Integrity Measurement Architecture +provides a mechanism to cryptographically sign the digest of a regular +file, and policies can be applied to e.g. require that code executed +by the root user have a valid signed digest.

+ +

The alignment between Linux IMA and ostree is quite strong. OSTree +provides a content-addressable object store, where files are intended +to be immutable. This is implemented with a basic read-only bind mount.

+ +

While IMA does not actually prevent mutating files, any changed (or unsigned) +files would (depending on policy) not be readable or executable.

+

+ + + IMA signatures and OSTree checksum + + +

+ + +

Mechanically, IMA signatures appear as a security.ima extended attribute +on the file. This is a signed digest of just the file content (and not +any metadata)

+ +

OSTree’s checksums in contrast include not just the file content, but also +metadata such as uid, gid and mode and extended attributes;

+ +

Together, this means that adding an IMA signature to a file in the OSTree +model appears as a new object (with a new digest). A nice property is that +this enables the transactional addition (or removal) of IMA signatures. +However, adding IMA signatures to files that were previously unsigned +also today duplicates disk space.

+

+ + + Signing + + +

+ + +

To apply IMA signatures to an OSTree commit, there is an ima-sign +command implemented currently in the ostree-rs-ext +project.

+

+ + + Generating a key + + +

+ + +

There is documentation for this in man evmctl and the upstream IMA +page; we will not replicate it here.

+

+ + + Signing a commit + + +

+ + +

ima-sign requires 4 things:

+ +
    +
  • An OSTree repository (could be any mode; archive or e.g. bare-user)
  • +
  • A ref or commit digest (e.g. exampleos/x86_64/stable)
  • +
  • A digest algorithm (usually sha256, but you may use e.g. sha512 as well)
  • +
  • An RSA private key
  • +
+ +

You can then add IMA signatures to all regular files in the commit:

+ +
$ ostree-ext-cli ima-sign --repo=repo exampleos/x86_64/stable sha256 /path/to/key.pem
+
+ +

Many different choices are possible for the signing model. For example, +your build system could store individual components/packages in their own +ostree refs, and sign them at build time. This would avoid re-signing +all binaries when creating production builds. Although note you +still likely want to sign generated artifacts from unioning individual +components, such as a dpkg/rpm database or equivalent and cache files +such as the ldconfig and GTK+ icon caches, etc.

+

+ + + Applying a policy + + +

+ + +

Signing a commit by itself will have little to no effect. You will also +need to include in your builds an IMA policy.

+

+ + + Linux EVM + + +

+ + +

The EVM subsystem builds on IMA, and adds another signature which +covers most file data, such as the uid, gid and mode and selected +security-relevant extended attributes.

+ +

This is quite close to the ostree native checksum - the ordering +of the fields is different so the checksums are physically different, but +logically they are very close.

+ +

However, the focus of the EVM design seems to mostly +be on machine-specific signatures with keys stored in a TPM. +Note that doing this on a per-machine basis would add a new +security.evm extended attribute, and crucially that +changes the ostree digest - so from ostree’s perspective, +these objects will appear corrupt.

+ +

In the future, ostree may learn to ignore the presence of security.evm +extended attributes.

+ +

There is also some support for “portable” EVM signatures - by +default, EVM signatures also include the inode number and generation +which are inherently machine-specific.

+ +

A future ostree enhancement may instead also focus on supporting +signing commits with these “portable” EVM signatures in addition to IMA.

+

+ + + Further references + + +

+ + +
    +
  • https://sourceforge.net/p/linux-ima/wiki/Home/
  • +
  • https://en.opensuse.org/SDB:Ima_evm
  • +
  • https://wiki.gentoo.org/wiki/Integrity_Measurement_Architecture
  • +
  • https://fedoraproject.org/wiki/Changes/Signed_RPM_Contents
  • +
  • https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_monitoring_and_updating_the_kernel/enhancing-security-with-the-kernel-integrity-subsystem_managing-monitoring-and-updating-the-kernel
  • +
+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/index.html b/index.html new file mode 100644 index 0000000000..3fd9c7744a --- /dev/null +++ b/index.html @@ -0,0 +1,498 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +libostree | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + +
+ +

+ + + libostree + + +

+ + +
    +
  1. Operating systems and distributions using OSTree
  2. +
  3. Distribution build tools
  4. +
  5. Projects linking to libostree
  6. +
  7. Language bindings
  8. +
  9. Building
  10. +
  11. API Reference
  12. +
  13. Manual Pages
  14. +
  15. Contact and discussion forums
  16. +
  17. Contributing
  18. +
  19. Licensing
  20. +
+ + + +

This project is now known as “libostree”, though it is still appropriate to use +the previous name: “OSTree” (or “ostree”). The focus is on projects which use +libostree’s shared library, rather than users directly invoking the command line +tools (except for build systems). However, in most of the rest of the +documentation, we will use the term “OSTree”, since it’s slightly shorter, and +changing all documentation at once is impractical. We expect to transition to +the new name over time.

+ +

As implied above, libostree is both a shared library and suite of command line +tools that combines a “git-like” model for committing and downloading bootable +filesystem trees, along with a layer for deploying them and managing the +bootloader configuration.

+ +

The core OSTree model is like git in that it checksums individual files and has +a content-addressed-object store. It’s unlike git in that it “checks out” the +files via hardlinks, and they thus need to be immutable to prevent corruption. +Therefore, another way to think of OSTree is that it’s just a more polished +version of +Linux VServer hardlinks.

+ +

Features:

+ +
    +
  • Transactional upgrades and rollback for the system
  • +
  • Replicating content incrementally over HTTP via GPG signatures and “pinned TLS” support
  • +
  • Support for parallel installing more than just 2 bootable roots
  • +
  • Binary history on the server side (and client)
  • +
  • Introspectable shared library API for build and deployment systems
  • +
  • Flexible support for multiple branches and repositories, supporting +projects like Flatpak which +use libostree for applications, rather than hosts.
  • +
+

+ + + Operating systems and distributions using OSTree + + +

+ + +

Apertis uses libostree for their host system as +well as Flatpak. See update documentation and +apertis-update-manager

+ +

Endless OS uses libostree for their host system as +well as Flatpak. See +their eos-updater +and deb-ostree-builder +projects.

+ +

For Debian/apt, see also https://github.com/stb-tester/apt2ostree +and the LWN article Merkle trees and build systems.

+ +

Fedora derivatives use rpm-ostree (noted below); there are 4 variants using OSTree:

+ + + +

Red Hat Enterprise Linux CoreOS is a derivative of Fedora CoreOS, used in OpenShift 4. +The machine-config-operator +manages upgrades. RHEL CoreOS is also the successor to RHEL Atomic Host, which +uses rpm-ostree as well.

+ +

Red Hat In-Vehicle Operating System (RHIVOS) is a derivative of CentOS Automotive Stream Distribution that uses OSTree, it’s closest Fedora derivative is Fedora IoT although it was created as it’s own distribution.

+ +

GNOME Continuous is +where OSTree was born - as a high performance continuous delivery/testing +system for GNOME.

+ +

GNOME OS is a testing OS that uses libostree for +their host system as well as Flatpak.

+ +

Liri OS has the option to install +their distribution using ostree.

+ +

Torizon OS +is a Linux distribution for embedded systems that updates via OSTree images +delivered via Uptane and +aktualizr.

+

+ + + Distribution build tools + + +

+ + +

meta-updater is +a layer available for OpenEmbedded +systems.

+ +

QtOTA is Qt’s over-the-air update framework +which uses libostree.

+ +

The BuildStream build and +integration tool supports importing and exporting from libostree repos.

+ +

fedora-iot/otto is a tool that helps +ship ostree commits inside Docker/OCI containers and run a webserver +to serve the commits.

+ +

Fedora coreos-assembler is +the build tool used to generate Fedora CoreOS derivatives.

+ +

debos is a tool-chain for simplifying the +process of building a Debian-based OS image.

+ +

gardenlinux/ostree-image-builder +is a sample for building Debian-based OS images. +It is not production ready but it might be useful to get started.

+

+ + + Projects linking to libostree + + +

+ + +

rpm-ostree is used by the +Fedora-derived operating systems listed above. It is a full hybrid +image/package system. By default it uses libostree to atomically replicate a base OS +(all dependency resolution is done on the server), but it supports “package layering”, where +additional RPMs can be layered on top of the base. This brings a “best of both worlds”” +model for image and package systems.

+ +

eos-updater is a daemon that implements updates +on EndlessOS.

+ +

Flatpak uses libostree for desktop +application containers. Unlike most of the other systems here, Flatpak does not +use the “libostree host system” aspects (e.g. bootloader management), just the +“git-like hardlink dedup”. For example, Flatpak supports a per-user OSTree +repository.

+ +

aktualizr is an +Uptane-conformant software update client library +intended for use in automotive and other security-sensitive embedded devices. +It uses OSTree to manage the OS of the host device by default.

+

+ + + Language bindings + + +

+ + +

libostree is accessible via GObject Introspection; +any language which has implemented the GI binding model should work. +For example, Both pygobject +and gjs are known to work +and further are actually used in libostree’s test suite today.

+ +

Some bindings take the approach of using GI as a lower level and +write higher level manual bindings on top; this is more common +for statically compiled languages. Here’s a list of such bindings:

+ + +

+ + + Building + + +

+ + +

Releases are available as GPG signed git tags, and most recent +versions support extended validation using +git-evtag.

+ +

However, in order to build from a git clone, you must update the +submodules. If you’re packaging OSTree and want a tarball, I +recommend using a “recursive git archive” script. There are several +available online; +this code +in OSTree is an example.

+ +

Once you have a git clone or recursive archive, building is the +same as almost every autotools project:

+ +
git submodule update --init
+env NOCONFIGURE=1 ./autogen.sh
+./configure --prefix=...
+make
+make install DESTDIR=/path/to/dest
+
+

+ + + API Reference + + +

+ + +

The libostree API documentation is available in Reference.

+

+ + + Manual Pages + + +

+ + +

The ostree manual pages are available in Manual.

+

+ + + Contact and discussion forums + + +

+ + +

There is also an #ostree channel on Libera.Chat as +well as enabled Github discussions.

+

+ + + Contributing + + +

+ + +

See Contributing.

+

+ + + Licensing + + +

+ + +

The licensing for the code of libostree can be canonically found in the individual files; +and the overall status in the COPYING +file in the source. Currently, that’s LGPLv2+. This also covers the man pages and API docs.

+ +

The license for the manual documentation in the doc/ directory is: +SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) +This is intended to allow use by Wikipedia and other projects.

+ +

In general, files should have a SPDX-License-Identifier and that is canonical.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/introduction/index.html b/introduction/index.html new file mode 100644 index 0000000000..50951060be --- /dev/null +++ b/introduction/index.html @@ -0,0 +1,441 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +OSTree Overview | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + OSTree Overview + + +

+ + +
    +
  1. Introduction
  2. +
  3. Hello World example
  4. +
  5. Comparison with “package managers”
  6. +
  7. Comparison with block/image replication
  8. +
  9. Atomic transitions between parallel-installable read-only filesystem trees
  10. +
+ + +

+ + + Introduction + + +

+ + +

OSTree is an upgrade system for Linux-based operating systems that +performs atomic upgrades of complete filesystem trees. It is +not a package system; rather, it is intended to complement them. +A primary model is composing packages on a server, and then +replicating them to clients.

+ +

The underlying architecture might be summarized as “git for +operating system binaries”. It operates in userspace, and will +work on top of any Linux filesystem. At its core is a git-like +content-addressed object store with branches (or “refs”) to track +meaningful filesystem trees within the store. Similarly, one can +check out or commit to these branches.

+ +

Layered on top of that is bootloader configuration, management of +/etc, and other functions to perform an upgrade beyond just +replicating files.

+ +

You can use OSTree standalone in the pure replication model, +but another approach is to add a package manager on top, +thus creating a hybrid tree/package system.

+

+ + + Hello World example + + +

+ + +

OSTree is mostly used as a library, but a quick tour of using its +CLI tools can give a general idea of how it works at its most +basic level.

+ +

You can create a new OSTree repository using init:

+ +
$ ostree --repo=repo init
+
+ +

This will create a new repo directory containing your +repository. Feel free to inspect it.

+ +

Now, let’s prepare some data to add to the repo:

+ +
$ mkdir tree
+$ echo "Hello world!" > tree/hello.txt
+
+ +

We can now import our tree/ directory using the commit +command:

+ +
$ ostree --repo=repo commit --branch=foo tree/
+
+ +

This will create a new branch foo pointing to the full tree +imported from tree/. In fact, we could now delete tree/ if we +wanted to.

+ +

To check that we indeed now have a foo branch, you can use the +refs command:

+ +
$ ostree --repo=repo refs
+foo
+
+ +

We can also inspect the filesystem tree using the ls and cat +commands:

+ +
$ ostree --repo=repo ls foo
+d00775 1000 1000      0 /
+-00664 1000 1000     13 /hello.txt
+$ ostree --repo=repo cat foo /hello.txt
+Hello world!
+
+ +

And finally, we can check out our tree from the repository:

+ +
$ ostree --repo=repo checkout foo tree-checkout/
+$ cat tree-checkout/hello.txt
+Hello world!
+
+

+ + + Comparison with “package managers” + + +

+ + +

Because OSTree is designed for deploying core operating +systems, a comparison with traditional “package managers” such +as dpkg and rpm is illustrative. Packages are traditionally +composed of partial filesystem trees with metadata and scripts +attached, and these are dynamically assembled on the client +machine, after a process of dependency resolution.

+ +

In contrast, OSTree only supports recording and deploying +complete (bootable) filesystem trees. It +has no built-in knowledge of how a given filesystem tree was +generated or the origin of individual files, or dependencies, +descriptions of individual components. Put another way, OSTree +only handles delivery and deployment; you will likely still want +to include inside each tree metadata about the individual +components that went into the tree. For example, a system +administrator may want to know what version of OpenSSL was +included in your tree, so you should support the equivalent of +rpm -q or dpkg -L.

+ +

The OSTree core emphasizes replicating read-only OS trees via +HTTP, and where the OS includes (if desired) an entirely +separate mechanism to install applications, stored in /var if they’re system global, or +/home for per-user +application installation. An example application mechanism is +http://docker.io/

+ +

However, it is entirely possible to use OSTree underneath a +package system, where the contents of /usr are computed on the client. +For example, when installing a package, rather than changing the +currently running filesystem, the package manager could assemble +a new filesystem tree that layers the new packages on top of a +base tree, record it in the local OSTree repository, and then +set it up for the next boot. To support this model, OSTree +provides an (introspectable) C shared library.

+

+ + + Comparison with block/image replication + + +

+ + +

OSTree shares some similarity with “dumb” replication and +stateless deployments, such as the model common in “cloud” +deployments where nodes are booted from an (effectively) +readonly disk, and user data is kept on a different volumes. +The advantage of “dumb” replication, shared by both OSTree and +the cloud model, is that it’s reliable +and predictable.

+ +

But unlike many default image-based deployments, OSTree supports +exactly two persistent writable directories that are preserved across +upgrades: /etc and /var.

+ +

Because OSTree operates at the Unix filesystem layer, it works +on top of any filesystem or block storage layout; it’s possible +to replicate a given filesystem tree from an OSTree repository +into plain ext4, BTRFS, XFS, or in general any Unix-compatible +filesystem that supports hard links. Note: OSTree will +transparently take advantage of some BTRFS features if deployed +on it.

+ +

OSTree is orthogonal to virtualization mechanisms like AMIs and qcow2 +images, though it’s most useful though if you plan to update stateful +VMs in-place, rather than generating new images.

+ +

In practice, users of “bare metal” configurations will find the OSTree +model most useful.

+

+ + + Atomic transitions between parallel-installable read-only filesystem trees + + +

+ + +

Another deeply fundamental difference between both package +managers and image-based replication is that OSTree is +designed to parallel-install multiple versions of multiple +independent operating systems. OSTree +relies on a new toplevel ostree directory; it can in fact +parallel install inside an existing OS or distribution +occupying the physical / root.

+ +

On each client machine, there is an OSTree repository stored +in /ostree/repo, and a set of “deployments” stored in /ostree/deploy/$STATEROOT/$CHECKSUM. +Each deployment is primarily composed of a set of hardlinks +into the repository. This means each version is deduplicated; +an upgrade process only costs disk space proportional to the +new files, plus some constant overhead.

+ +

The model OSTree emphasizes is that the OS read-only content +is kept in the classic Unix /usr; it comes with code to +create a Linux read-only bind mount to prevent inadvertent +corruption. There is exactly one /var writable directory shared +between each deployment for a given OS. The OSTree core code +does not touch content in this directory; it is up to the code +in each operating system for how to manage and upgrade state.

+ +

Finally, each deployment has its own writable copy of the +configuration store /etc. On upgrade, OSTree will +perform a basic 3-way diff, and apply any local changes to the +new copy, while leaving the old untouched.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/man/index.html b/man/index.html new file mode 100644 index 0000000000..87c511e4d5 --- /dev/null +++ b/man/index.html @@ -0,0 +1 @@ +OSTree Manual diff --git a/man/ostree-admin-cleanup.html b/man/ostree-admin-cleanup.html new file mode 100644 index 0000000000..b8d8c80677 --- /dev/null +++ b/man/ostree-admin-cleanup.html @@ -0,0 +1,3 @@ +ostree admin cleanup

Name

ostree-admin-cleanup — Delete untagged deployments and repository objects

Synopsis

ostree admin cleanup

Description

+ OSTree sysroot cleans up other bootversions and old deployments. If/when a pull or deployment is interrupted, a partially written state may remain on disk. This command cleans up any such partial states. +

Example

$ ostree admin cleanup

diff --git a/man/ostree-admin-config-diff.html b/man/ostree-admin-config-diff.html new file mode 100644 index 0000000000..1fff9e5277 --- /dev/null +++ b/man/ostree-admin-config-diff.html @@ -0,0 +1,8 @@ +ostree admin config-diff

Name

ostree-admin-config-diff — Diff current /etc configuration versus default

Synopsis

ostree admin config-diff [OPTIONS...]

Description

+ Prints the differences between the current /etc directory and the default configuration in /usr/etc. Newly added files (present in /etc but not in /usr/etc) will be prefixed with 'A'. Modified files will be prefixed with 'M', and deleted files with 'D'. +

Options

--os="STATEROOT"

+ Use a different operating system stateroot than the current one. +

Example

$ ostree admin config-diff

+        M   shadow
+        A   example.txt
+	
diff --git a/man/ostree-admin-deploy.html b/man/ostree-admin-deploy.html new file mode 100644 index 0000000000..d7d661f670 --- /dev/null +++ b/man/ostree-admin-deploy.html @@ -0,0 +1,42 @@ +ostree admin deploy

Name

ostree-admin-deploy — Checkout a revision as the new default deployment

Synopsis

ostree admin deploy [OPTIONS...] {REFSPEC}

Description

+ Takes a commit or revision REFSPEC, and queues the new deployment as default upon reboot. +

Options

--stateroot="STATEROOT"

+ Use a different operating system stateroot than the current one. +

--os="STATEROOT"

+ Alias for --stateroot. +

--origin-file="FILENAME"

+ Use FILENAME as the origin, which is where OSTree will look for updated versions of the tree. +

--retain

+ Do not delete previous deployment. +

--retain-pending

+ Do not delete pending deployments. +

--retain-rollback

+ Do not delete rollback deployments. +

--not-as-default

+ Append rather than prepend new deployment. +

--lock-finalization

+ The deployment will not be "finalized" by default on shutdown; to later + queue it, use ostree admin lock-finalization --unlock. +

--karg-proc-cmdline

+ Import current /proc/cmdline. +

--karg="NAME=VALUE"

+ Set kernel argument, like root=/dev/sda1; this overrides any earlier argument with the same name. +

--karg-append="NAME=VALUE"

+ Append kernel argument; useful with e.g. console= that can be used multiple times. +

--karg-delete="NAME=VALUE"

+ Delete kernel argument if exists, can be used multiple times. +

Example

$ ostree admin status

+        * gnome-ostree 67e382b11d213a402a5313e61cbc69dfd5ab93cb07.0
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+          gnome-ostree ce19c41036cc45e49b0cecf6b157523c2105c4de1ce3.0
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+

$ ostree admin deploy gnome-ostree/buildmain/x86_64-runtime

+        ostadmin: Creating deployment /ostree/deploy/gnome-ostree/deploy/7e382b11d213a402a5313e61cbc69dfd5ab93cb07.1
+        ostadmin: Processing /etc: 3 modified, 0 removed, 29 added
+        Transaction complete: bootconfig swap: no deployment count change: 0)
+

$ ostree admin status

+          gnome-ostree 67e382b11d213a402a5313e61cbc69dfd5ab93cb07.1
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+        * gnome-ostree 67e382b11d213a402a5313e61cbc69dfd5ab93cb07.0
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+
diff --git a/man/ostree-admin-init-fs.html b/man/ostree-admin-init-fs.html new file mode 100644 index 0000000000..5535fac10e --- /dev/null +++ b/man/ostree-admin-init-fs.html @@ -0,0 +1,5 @@ +ostree admin init-fs

Name

ostree-admin-init-fs — Initialize a new root filesystem

Synopsis

ostree admin init-fs [OPTIONS...] {PATH}

Description

+ Initialize an empty physical root filesystem in the designated PATH, with normal toplevels and correct permissions for each directory. Primarily useful for operating system installers. +

Example

$ mkdir /example

$ ostree admin init-fs /example

$ ls /example

+ boot dev home ostree proc root run sys tmp +

diff --git a/man/ostree-admin-instutil.html b/man/ostree-admin-instutil.html new file mode 100644 index 0000000000..fa486faabc --- /dev/null +++ b/man/ostree-admin-instutil.html @@ -0,0 +1,10 @@ +ostree admin instutil

Name

ostree-admin-instutil — Utility functions intended primarily for operating system installation programs

Synopsis

ostree admin instutil {SUBCOMMAND} [ARGS]

Description

+ Use the subcommands to toggle admin installation utilities for selinux policies and kernel arguments. +

Subcommands

selinux-ensure-labeled [SUBPATH PREFIX]

+ Ensure all files and directories are labeled according to SELinux policy of the first deployment. +

set-kargs [--merge] [--import-proc-cmdline] [--append="NAME=VALUE"] [--replace="NAME=VALUE"] [MORE_APPEND_ARGS]

+ Replace the kernel arguments of the default deployment. The new arguments are based + on an empty list (the default), the current options (--merge), or the arguments + of the loaded kernel (--import-proc-cmdline), and new options either are added to the + end (--append="NAME=VALUE") or replace existing arguments of the same name (--replace="NAME=VALUE"). +

diff --git a/man/ostree-admin-lock-finalization.html b/man/ostree-admin-lock-finalization.html new file mode 100644 index 0000000000..bd9fc87cca --- /dev/null +++ b/man/ostree-admin-lock-finalization.html @@ -0,0 +1,14 @@ +ostree admin lock-finalization

Name

ostree-admin-lock-finalization — Change whether staged deployment will be queued for next boot

Synopsis

ostree admin lock-finalization [OPTIONS...]

Description

+ This command requires a staged deployment. By default, this command ensures the deployment + will be set into a "finalization locked" state, which means it will not be queued for the next boot by default. +

+ This is the same as the --lock-finalization argument for ostree admin deploy, + which is the recommended way to use this feature in a race-free way. +

+ However more commonly, one will use the --unlock argument for this command to later unlock + a deployment which was finalization locked. +

Options

--sysroot="PATH"

+ Path to the system to use rather than the current one. +

--unlock,-u

+ Unlock the deployment finalization state. +

diff --git a/man/ostree-admin-os-init.html b/man/ostree-admin-os-init.html new file mode 100644 index 0000000000..1b49f470f7 --- /dev/null +++ b/man/ostree-admin-os-init.html @@ -0,0 +1,3 @@ +ostree admin os-init

Name

ostree-admin-os-init — Soft-deprecated alias for stateroot-init

Synopsis

ostree admin os-init {STATEROOT}

Description

+ This is a soft-deprecated alias for stateroot-init. Please see the documentation for that. +

diff --git a/man/ostree-admin-pin.html b/man/ostree-admin-pin.html new file mode 100644 index 0000000000..5f0c29c0e1 --- /dev/null +++ b/man/ostree-admin-pin.html @@ -0,0 +1,9 @@ +ostree admin pin

Name

ostree-admin-pin — Explicitly retain deployment at a given index

Synopsis

ostree admin pin {INDEX}

Description

+ Ensures the deployment at INDEX, will not be garbage + collected by default. This is termed "pinning". If the + -u option is provided, undoes a pinning operation. + INDEX can be >= 0 or one of booted, pending or + rollback strings. +

Options

--unpin,-u

+ Undoes a pinning operation. +

diff --git a/man/ostree-admin-post-copy.html b/man/ostree-admin-post-copy.html new file mode 100644 index 0000000000..ed52b68818 --- /dev/null +++ b/man/ostree-admin-post-copy.html @@ -0,0 +1,7 @@ +ostree admin post-copy

Name

ostree-admin-post-copy — Fix up sysroot after a (file based) copy

Synopsis

ostree admin post-copy [OPTIONS...]

Description

+ Applies any fixes to a sysroot that are needed after having copyed it file by file. + This includes enabling fs-verity to any files that lack it, which can happen if + you copy a file. +

Options

--sysroot="PATH"

+ Path to the system to use rather than the current one. +

diff --git a/man/ostree-admin-set-default.html b/man/ostree-admin-set-default.html new file mode 100644 index 0000000000..8051b205e4 --- /dev/null +++ b/man/ostree-admin-set-default.html @@ -0,0 +1,16 @@ +ostree admin set-default

Name

ostree-admin-set-default — Make deployment at a given index the default for the next boot

Synopsis

ostree admin set-default {INDEX}

Description

+ Make the deployment at INDEX the default for the next boot. +

Example

$ ostree admin status

+        * exampleos 67e382b11d213a402a5313e61cbc69dfd5ab93cb07.0
+            origin refspec: exampleos/buildmain/x86_64-runtime
+          exampleos ce19c41036cc45e49b0cecf6b157523c2105c4de1c.0
+            origin refspec: exampleos/buildmain/x86_64-runtime
+

$ ostree admin set-default 1

+        Transaction complete; bootconfig swap: deployment count change: 0
+

$ ostree admin status

+ exampleos ce19c41036cc45e49b0cecf6b157523c2105c4de1c.0 + origin refspec: exampleos/buildmain/x86_64-runtime + * exampleos 67e382b11d213a402a5313e61cbc69dfd5ab93cb07.0 + origin refspec: exampleos/buildmain/x86_64-runtime +
+
diff --git a/man/ostree-admin-set-origin.html b/man/ostree-admin-set-origin.html new file mode 100644 index 0000000000..6d8f447e34 --- /dev/null +++ b/man/ostree-admin-set-origin.html @@ -0,0 +1,12 @@ +ostree admin set-origin

Name

ostree-admin-set-origin — Change the "origin" (location for upgrades)

Synopsis

ostree admin set-origin {REMOTENAME} {URL} [BRANCH]

Description

+ Add a new remote named + REMOTENAME (if it does not + already exist). Then change the origin file for the + current deployment. This is the ref that will be + "tracked" and upgraded with ostree admin + upgrade. +

Options

--set=KEY=VALUE

+ Set an option for the remote. +

--index=INDEX

Change the origin of the deployment + numbered INDEX (starting + from 0).

Example

$ ostree admin set-origin exampleos http://os.example.com/repo exampleos/10.0/main/router

diff --git a/man/ostree-admin-stateroot-init.html b/man/ostree-admin-stateroot-init.html new file mode 100644 index 0000000000..18686ce844 --- /dev/null +++ b/man/ostree-admin-stateroot-init.html @@ -0,0 +1,9 @@ +ostree admin stateroot-init

Name

ostree-admin-stateroot-init — Initialize empty state for a given operating system

Synopsis

ostree admin stateroot-init {STATEROOT}

Description

+ Initializes an new stateroot (AKA "osname") for an operating system. + Ensures that the core subdirectories of /var (/tmp, /lib, /run, and + /lock) exist and initialize the given STATEROOT as OSTree stateroot. + Each deployment location is comprised of a single shared + var and a set of deployments (chroots). +

Example

$ ostree admin stateroot-init exampleos

+        ostree/deploy/exampleos initialized as OSTree stateroot
+    
diff --git a/man/ostree-admin-status.html b/man/ostree-admin-status.html new file mode 100644 index 0000000000..51b959fa4e --- /dev/null +++ b/man/ostree-admin-status.html @@ -0,0 +1,25 @@ +ostree admin status

Name

ostree-admin-status — List deployments

Synopsis

ostree admin status

Description

+ Lists the deployments available to be booted into. Includes osname, the checksum followed by the deploy serial, and the refspec. An asterisk indicates the current booted deployment. +

Options

--sysroot="PATH"

+ Create a new OSTree sysroot at PATH +

-V, --verify

+ Print the commit verification status +

-S, --skip-signatures

+ Skip signatures in output +

-D, --is-default

+ Output the string default if the default deployment + is the booted one, not-default if we are booted in + a non-default deployment (e.g. the user interactively chose a + different entry in the bootloader menu, or the bootloader rolled back + automatically, etc.). If we are not in a booted OSTree system, an + error is returned. +

-v, --verbose

+ Print debug information during command processing +

--version

+ Print version information and exit +

Example

$ ostree admin status

+        * gnome-ostree 67e382b11d213a402a5313e61cbc69dfd5ab93cb07.0
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+          gnome-ostree ce19c41036cc45e49b0cecf6b157523c2105c4de1c.0
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+
diff --git a/man/ostree-admin-switch.html b/man/ostree-admin-switch.html new file mode 100644 index 0000000000..4408b3a658 --- /dev/null +++ b/man/ostree-admin-switch.html @@ -0,0 +1,5 @@ +ostree admin switch

Name

ostree-admin-switch — Construct new tree from current origin and deploy it, if it changed

Synopsis

ostree admin switch {REF}

Description

+ Choose a different REF from the current remote to track. This is the ref that will be "tracked" and upgraded with ostree admin upgrade. Like an upgrade, the operating system state will be preserved. +

Options

--os="STATEROOT"

+ Use a different operating system root than the current one. +

Example

$ ostree admin switch fedostree/20/workstation/gnome/core

diff --git a/man/ostree-admin-undeploy.html b/man/ostree-admin-undeploy.html new file mode 100644 index 0000000000..21f930ec6f --- /dev/null +++ b/man/ostree-admin-undeploy.html @@ -0,0 +1,15 @@ +ostree admin undeploy

Name

ostree-admin-undeploy — Delete deployment at a given index

Synopsis

ostree admin undeploy {INDEX}

Description

+ Deletes the deployment at INDEX. INDEX must be in range and not reference the currently booted deployment. +

Example

$ ostree admin status

+        * gnome-ostree 67e382b11d213a402a5313e61cbc69dfd5ab93cb07.0
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+          gnome-ostree ce19c41036cc45e49b0cecf6b157523c2105c4de1c.0
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+

$ ostree admin undeploy 1

+        Transaction complete; bootconfig swap: no deployment count change: -1)
+        Freed objects: 326.5 kB
+        Deleted deployment ce19c41036cc45e49b0cecf6b157523c2105c4de1c.0
+

$ ostree admin status

+        * gnome-ostree 67e382b11d213a402a5313e61cbc69dfd5ab93cb07.0
+            origin refspec: gnome-ostree/buildmain/x86_64-runtime
+
diff --git a/man/ostree-admin-unlock.html b/man/ostree-admin-unlock.html new file mode 100644 index 0000000000..805e0d6dae --- /dev/null +++ b/man/ostree-admin-unlock.html @@ -0,0 +1,16 @@ +ostree admin unlock

Name

ostree-admin-unlock — Prepare the current deployment for hotfix or development

Synopsis

ostree admin unlock [OPTIONS...]

Description

+ Remove the read-only bind mount on /usr + and replace it with a writable overlay filesystem. This + default invocation of "unlock" is intended for + development/testing purposes. All changes in the overlay + are lost on reboot. However, this command also supports + "hotfixes", see below. +

Options

--hotfix

If this option is provided, the + current deployment will be cloned as a rollback + target. This option is intended for things like + emergency security updates to userspace components + such as sshd. The semantics here + differ from the default "development" unlock mode + in that reboots will retain any changes (which is what + you likely want for security hotfixes). +

diff --git a/man/ostree-admin-upgrade.html b/man/ostree-admin-upgrade.html new file mode 100644 index 0000000000..451c39d7e2 --- /dev/null +++ b/man/ostree-admin-upgrade.html @@ -0,0 +1,25 @@ +ostree admin upgrade

Name

ostree-admin-upgrade — Construct new tree from current origin and deploy it, if it changed

Synopsis

ostree admin upgrade [OPTIONS...]

Description

+ Downloads the latest version of the current ref from the build + server and deploys it, if it changed. Reboot the machine for the + changes to take effect. These phases can be split via + --pull-only and --deploy-only. +

Options

--os="STATEROOT"

+ Use a different operating system root than the current one. +

--pull-only

Only perform a pull into the repository; do not + create a deployment. This option can hence safely be used in a + background scheduled job with the assurance of not changing + system state.

--deploy-only

Create a new deployment from the latest commit + in the tracked origin refspec. This option is intended to be used + by a scheduled system that detected changes via --pull-only, + and is ready to deploy them.

--stage

+ Perform deployment finalization at shutdown time. Recommended, + and will likely become the default in the future. +

--reboot,-r

+ Reboot after a successful upgrade. +

--allow-downgrade

+ Permit deployment of chronologically older trees. +

--override-commit="CHECKSUM"

+ Deploy CHECKSUM instead of the latest tree. +

Example

$ ostree admin upgrade

+        No update available.
+
diff --git a/man/ostree-admin.html b/man/ostree-admin.html new file mode 100644 index 0000000000..f6c881aa56 --- /dev/null +++ b/man/ostree-admin.html @@ -0,0 +1,9 @@ +ostree admin

Name

ostree-admin — Use one of the ostree admin commands

Synopsis

ostree admin {SUBCOMMAND}

Description

+ Use ostree admin subcommands. +

Subcommands

  • cleanup

  • config-diff

  • deploy

  • init-fs

  • instutil

  • os-init

  • pin

  • post-copy

  • set-origin

  • status

  • switch

  • undeploy

  • unlock

  • upgrade

+ View manpages for each admin subcommand using, for example: +

+ $ man ostree-admin cleanup +

Options

--help, -h

Usage help

--sysroot="PATH"

Creates a new OSTree sysroot at PATH

--print-current-dir

+ Prints the full path to the deployment directory for the currently active deployment in the specified sysroot to standard out. This is incompatible with specifying a subcommand. +

diff --git a/man/ostree-cat.html b/man/ostree-cat.html new file mode 100644 index 0000000000..b8d5194624 --- /dev/null +++ b/man/ostree-cat.html @@ -0,0 +1,5 @@ +ostree cat

Name

ostree-cat — Display or concatenate contents of files

Synopsis

ostree cat {COMMIT} {PATH...}

Description

+ This command functions much like the typical Unix "cat" command, in that it displays the contents of a file, or concatenates them given two or more files. However, this command requires the user to specify a commit - a checksum or refspec corresponding to a given build. If you use a refspec, OSTree will refer to the most recent commit, unless you specify a parent build using the carat (^) at the end of the refspec. It will then operate the command in that given commit. +

Example

$ ostree cat my-branch helloworld.txt

+        Hello, world!
+
diff --git a/man/ostree-checkout.html b/man/ostree-checkout.html new file mode 100644 index 0000000000..1dac038445 --- /dev/null +++ b/man/ostree-checkout.html @@ -0,0 +1,50 @@ +ostree checkout

Name

ostree-checkout — Check out a commit into a filesystem

Synopsis

ostree checkout [OPTIONS...] {COMMIT} [DESTINATION]

Description

+ Checks out the given commit into the filesystem under directory DESTINATION. If DESTINATION is not specified, the COMMIT will become the destination checkout target. If COMMIT destination already exists, command will error unless --union option is selected. +

Options

--user-mode, -U

+ Do not change file ownership or initialize extended attributes. +

--subpath="PATH"

+ Checkout sub-directory PATH. +

--union

+ Keep existing directories and unchanged files, overwrite existing files. +

--union-add

+ Keep existing directories and files. +

--union-identical

Like --union, but error out + if a file would be replaced with a different file. Add new files + and directories, ignore identical files, and keep existing + directories. Requires -H.

--whiteouts

+ Process whiteout files (Docker style). +

--process-passthrough-whiteouts

+ Enable overlayfs whiteout extraction into 0:0 character devices. + Overlayfs whiteouts are encoded inside ostree as .ostree-wh.filename + and extracted as 0:0 character devices. This is useful to carry + container storage embedded into ostree. +

--allow-noent

+ Do nothing if specified path does not exist. +

--from-stdin

+ Process many checkouts from standard input. +

--from-file="FILE"

+ Process many checkouts from input file. +

--fsync="POLICY"

+ POLICY is a boolean which specifies whether fsync should be + used or not. Default to true. +

--require-hardlinks, + -H

+ Do not fall back to full copies if hardlinking fails. +

--force-copy-zerosized, + -z

+ This option does nothing; the functionality is now always on by default. +

--force-copy, -C

+ Never hardlink (but may reflink if available). +

--bareuseronly-dirs, + -M

+ Suppress mode bits outside of 0775 for directories (suid, + world writable, etc.). +

--skip-list="FILE"

+ Skip checking out the absolute file paths listed in FILE, + one per line. +

--selinux-policy

+ Set SELinux labels based on policy in root filesystem PATH + (may be /). This implies --force-copy. +

Example

$ ostree checkout my-branch

$ ls

+        file1file2my-branch
+
diff --git a/man/ostree-checksum.html b/man/ostree-checksum.html new file mode 100644 index 0000000000..37c2159862 --- /dev/null +++ b/man/ostree-checksum.html @@ -0,0 +1,7 @@ +ostree checksum

Name

ostree-checksum — Checksum a file or directory

Synopsis

ostree checksum {PATH}

Description

+ Generates a checksum for a given file or directory. +

Options

--ignore-xattrs

+ Ignore extended attributes when checksumming. +

Example

$ ostree checksum file1

+        67e382b11d213a402a5313e61cbc69dfd5ab93cb07fbb8b71c2e84f79fa5d7dc
+
diff --git a/man/ostree-commit.html b/man/ostree-commit.html new file mode 100644 index 0000000000..e92c573544 --- /dev/null +++ b/man/ostree-commit.html @@ -0,0 +1,89 @@ +ostree commit

Name

ostree-commit — Commit a new revision

Synopsis

ostree commit [OPTIONS...] --branch= {BRANCH} [PATH]

Description

+ This allows you to commit changes to a branch. The specification of the branch is required. The command will print the checksum of a successful commit. +

Options

--subject, -s="SUBJECT"

+ One line subject. (optional) +

--body, -m="BODY"

+ Full description. (optional) +

--body-file, -F="FILE"

+ Full commit description from a file. (optional) +

--editor, -e

+ Open a text editor for the commit description. It will use OSTREE_EDITOR, VISUAL, EDITOR, or vi, in descending order of preference. The commit will be aborted if the message is left empty. +

--branch, -b="BRANCH"

+ Branch. Required, unless --orphan is given. +

--parent="COMMIT"

+ Parent checksum or "none" to explicitly use no parent. If not specified, BRANCH is used as parent (no parent in case BRANCH does not exist). +

--tree="dir=PATH" or "tar=TARFILE" or "ref=COMMIT"

+ Overlay the given argument as a tree. When committing an archive, the TARFILE can be specified as - to read the archive from standard input. +

--base="REV"

+ Start from the content in a commit. This differs from --tree=ref=REV in that no commit modifiers are applied. This is usually what you want when + creating a derived commit. This is also used for --selinux-policy-from-base. +

--add-metadata-string="KEY=VALUE"

+ Add a key/value pair to metadata. Can be specified multiple times. +

--add-metadata="KEY=VALUE"

+ Add a key/value pair to metadata, where the KEY is a string, and VALUE is g_variant_parse() formatted. Can be specified multiple times. +

--keep-metadata="KEY"

+ Keep metadata KEY and its associated VALUE from parent. Can be specified multiple times. +

--add-detached-metadata-string="KEY=VALUE"

+ Add a key/value pair to detached metadata. +

--owner-uid="UID"

+ Set file ownership user id. +

--owner-gid="GID"

+ Set file ownership group id. +

--no-xattrs

+ Do not import extended attributes. +

--selinux-labeling-epoch0 | 1

+ When SELinux labeling is enabled, epoch 1 ensures that /usr/etc is labeled as if it was /etc. +

--bootable

+ Inject standard metadata for a bootable Linux filesystem tree. +

--link-checkout-speedup

+ Optimize for commits of trees composed of hardlinks into the repository. +

--tar-autocreate-parents

+ When loading tar archives, automatically create parent directories as needed. +

--skip-if-unchanged

+ If the contents are unchanged from previous commit, do nothing. +

--consume

+ When committing from a local directory (i.e. not an archive or --tree=ref), + assume ownership of the content. This may simply involve deleting it, + but if possible, the content may simply be rename()ed + into the repository rather than creating a new copy. +

--statoverride="PATH"

+ File containing list of modifications to make permissions (file mode in + decimal, followed by space, followed by file path). The specified mode + is ORed with the file's original mode unless preceded by "=". +

--skip-list="PATH"

+ File containing list of file paths to skip (one path per line). +

--table-output

+ Output more information in a KEY: VALUE format. +

--generate-sizes

+ Generate size information along with commit metadata. +

--gpg-sign="KEY-ID"

+ GPG Key ID with which to sign the commit (if have GPGME - GNU Privacy Guard Made Easy). +

--gpg-homedir="HOMEDIR"

+ GPG home directory to use when looking for keyrings (if have GPGME - GNU Privacy Guard Made Easy). +

--timestamp="TIMESTAMP"

+ Override the timestamp of the commit to TIMESTAMP. +

--orphan

+ Create a commit without writing to a ref (branch) +

--fsync="POLICY"

+ POLICY is a boolean which specifies whether fsync should be used or not. Default to true. +

-s, --sign-type

+ Use particular signature engine. Currently + available ed25519 and dummy + signature types. + + The default is ed25519 . +

--sign-from-file="PATH"

+ This will read a key (corresponding to the provided --sign-type from the provided path. The key should be base64 encoded. +

--sign="KEY-ID"

+ In new code, avoid using this because passing private keys via command line arguments + are prone to leakage in logs and process listings. +

+ The KEY-ID is: +

for ed25519:

+ base64-encoded secret key for commit signing. +

for dummy:

+ ASCII-string used as secret key. +

+

Example

$ ostree commit --branch=my-branch --subject="Initial commit"

+        67e382b11d213a402a5313e61cbc69dfd5ab93cb07fbb8b71c2e84f79fa5d7dc
+
diff --git a/man/ostree-config.html b/man/ostree-config.html new file mode 100644 index 0000000000..07efa02370 --- /dev/null +++ b/man/ostree-config.html @@ -0,0 +1,14 @@ +ostree config

Name

ostree-config — Change configuration settings

Synopsis

ostree config get {GROUPNAME.KEYNAME}

ostree config get { --group=GROUPNAME} { KEYNAME}

ostree config set {GROUPNAME.KEYNAME} {VALUE}

ostree config set { --group=GROUPNAME} { KEYNAME} {VALUE}

ostree config unset {GROUPNAME.KEYNAME}

ostree config unset { --group=GROUPNAME} { KEYNAME}

Description

  • + ostree config get displays the value of + KEYNAME in the group GROUPNAME +

  • + ostree config set sets the value of + KEYNAME in the group GROUPNAME + to VALUE . +

  • + ostree config unset removes the key + KEYNAME from the group GROUPNAME + so that OSTree uses the default value for it. It is not an + error for the specified GROUPNAME or + KEYNAME not to exist. +

Example

$ ostree config get core.mode

bare

$ ostree config set --group='remote "myremote"' url http://example.com/repo

$ ostree config unset core.lock-timeout-secs

diff --git a/man/ostree-create-usb.html b/man/ostree-create-usb.html new file mode 100644 index 0000000000..cb7e1f30f3 --- /dev/null +++ b/man/ostree-create-usb.html @@ -0,0 +1,35 @@ +ostree create-usb

Name

ostree-create-usb — Put the given refs on an external drive for P2P distribution.

Synopsis

ostree create-usb [OPTIONS...] {MOUNT-PATH} {COLLECTION-ID REF} [COLLECTION-ID REF...]

Description

+ This command creates a repository in MOUNT-PATH and pulls the given + REF(s) into it so they can be found and pulled from (perhaps by another computer that's offline). + See + ostree-find-remotes(1) + for more information on P2P distribution. +

+ In order for ostree to pull refs from a mounted filesystem (such as + a USB drive) the repo must be in a standard location. Specifically, + subdirectories of .ostree/repos.d are checked, + then .ostree/repo, ostree/repo, + and var/lib/flatpak/repo are checked. By default + ostree create-usb uses .ostree/repo, + but if you specify another location using --destination-repo + a symbolic link will be created for you in .ostree/repos.d. +

+ This command will regenerate the summary file + in the destination repo so that it stays accurate, so you shouldn't + try to use summary signatures in the destination repo. This + shouldn't be a concern because clients that support pulling from + USB mounts use signed per-repo and per-commit metadata instead of + summary signatures. +

Options

--disable-fsync

+ Do not invoke fsync(). +

--destination-repo=DEST

+ Create the repository in DEST under MOUNT-PATH, rather than + the default location. +

--commit=COMMIT

+ Pull COMMIT instead of whatever REF points to. This can only + be used if a single ref is specified. +

Example

ostree --repo=/var/lib/flatpak/repo create-usb /run/media/mwleeds/f6d04c7a-60f6-4ba3-bb96-0f40498675be com.exampleos.Apps app/org.kde.Khangman/x86_64/stable com.exampleos.Apps ostree-metadata com.exampleos.Apps appstream/x86_64

+
+5 metadata, 213 content objects imported; 1 KiB transferred in 1 seconds                                                                                                                      Copied 3/3 refs successfully from ‘/var/lib/flatpak/repo’ to ‘.ostree/repo’ repository in ‘/run/media/mwleeds/f6d04c7a-60f6-4ba3-bb96-0f40498675be’.
+
+
diff --git a/man/ostree-diff.html b/man/ostree-diff.html new file mode 100644 index 0000000000..a394d9ffe3 --- /dev/null +++ b/man/ostree-diff.html @@ -0,0 +1,17 @@ +ostree diff

Name

ostree-diff — Compare a directory against a revision

Synopsis

ostree diff [OPTIONS...] {REV_OR_DIR} {REV_OR_DIR}

Description

+ Compare a directory or revision against another directory or revision. If REV_OR_DIR starts with `/` or `./`, it is interpreted as a directory, otherwise a revision. Shows files and directories modified, added, and deleted. If there is a file in the second REV_OR_DIR not in the first, it will show with an "A" for "added". If a file in the first REV_OR_DIR is not in the second, it shows "D" for "deleted". "M" for "modified" will also show. +

Options

--stats

+ Print various statistics. +

--fs-diff

+ Print filesystem diff. +

--owner-uid

+ Use file ownership user id for local files. +

--owner-gid

+ Use file ownership group id for local files. +

Example

$ ostree diff my-branch^ my-branch

+        A   /testdirectory
+        M   /helloworld.txt
+

$ ostree diff my-branch my-branch^

+        D   /testdirectory
+        M   /helloworld.txt
+
diff --git a/man/ostree-export.html b/man/ostree-export.html new file mode 100644 index 0000000000..501fab8370 --- /dev/null +++ b/man/ostree-export.html @@ -0,0 +1,5 @@ +ostree export

Name

ostree-export — Generate a tar archive from an OSTree commit

Synopsis

ostree export [OPTIONS...] {BRANCH}

Description

+ This command generates a GNU tar formatted archive from an + OSTree commit. This is useful for cases like backups, + converting OSTree commits into Docker images, and the like. +

Example

$ ostree export exampleos/x86_64/standard | gzip > exampleos-standard.tar.gz

diff --git a/man/ostree-find-remotes.html b/man/ostree-find-remotes.html new file mode 100644 index 0000000000..063b983bac --- /dev/null +++ b/man/ostree-find-remotes.html @@ -0,0 +1,47 @@ +ostree find-remotes

Name

ostree-find-remotes — Find remotes to serve the given refs

Synopsis

ostree find-remotes [OPTIONS...] {COLLECTION-ID} {REF} [COLLECTION-ID REF...]

Description

+ OSTree has the ability to pull not just from the configured remote + servers but also from peer computers on the LAN and from mounted + filesystems such as USB drives. This functionality requires the use + of collection IDs and GPG verification. +

+ The find-remotes command searches for remotes + which claim to provide one or more of the given COLLECTION-ID REF + pairs and prints information about them, with remotes sorted by + latency (Mounts > LAN > Internet). By default, OSTree searches for + remotes in configuration files, on mounted filesystems (in a + well-known location), and on the LAN using Avahi. Searching for LAN + remotes requires OSTree to have been compiled with Avahi support, + and it requires an Avahi daemon to be running. You can override the + default set of finders (sources for remotes) using the + --finders option documented below. +

+ The create-usb command is the recommended way to + put refs on a USB such that find-remotes will + discover them. See + ostree-create-usb(1). +

Options

--cache-dir=DIR

+ Use an alternate cache directory in DIR. +

--disable-fsync

+ Do not invoke fsync(). +

--finders=FINDERS

+ Use the specified comma separated list of finders rather than + the default set. Possible values: config, + lan, and mount (or any + combination thereof). +

--pull

+ Pull the most recent commit found for each ref. +

--mirror

+ Do a mirror pull (see the documentation for + ostree pull --mirror). This option can + only be used in combination with --pull. +

Example

$ ostree find-remotes --finders=mount,lan com.exampleos.Os exampleos/x86_64/standard

+Result 0: http://10.0.64.202:43381/0
+ - Finder: OstreeRepoFinderAvahi
+ - Keyring: exampleos.trustedkeys.gpg
+ - Priority: 60
+ - Summary last modified: 2018-01-12T19:00:28Z
+ - Refs:
+    - (com.exampleos.Os, exampleos/x86_64/standard) = c91acd964b3fda561b87bfb7f7c80e36220d76b567f0ce90c0e60742ef33c360
+
+1/1 refs were found.
+
diff --git a/man/ostree-fsck.html b/man/ostree-fsck.html new file mode 100644 index 0000000000..202353a978 --- /dev/null +++ b/man/ostree-fsck.html @@ -0,0 +1,25 @@ +ostree fsck

Name

ostree-fsck — Check the repository for consistency

Synopsis

ostree fsck [OPTIONS...]

Description

+ Checks the repository to verify the content integrity of commit objects. Looks for missing and corrupted objects and metadata, and validates directory structure and metadata. +

Options

--quiet,-q

+ Only print error messages. +

--delete

+ Remove corrupted objects. +

--add-tombstones

+ Add tombstone commit for referenced but missing commits. +

--verify-bindings

+ Verify that the commits pointed to by each ref have that + ref in the binding set. You should usually add this + option; it only defaults to off for backwards compatibility. +

--verify-back-refs

+ Verify that all the refs listed in a commit’s ref-bindings + point to that commit. This cannot be used in repositories + where the target of refs is changed over time as new commits + are added, but can be used in repositories which are + regenerated from scratch for each commit. + Implies --verify-bindings as well. +

Example

$ ostree fsck

+        Enumerating objects...
+        Verifying content integrity of of 2 commit objects
+        0/2572 objects
+        2571/2572 objects
+
diff --git a/man/ostree-gpg-sign.html b/man/ostree-gpg-sign.html new file mode 100644 index 0000000000..1e23304aaf --- /dev/null +++ b/man/ostree-gpg-sign.html @@ -0,0 +1,10 @@ +ostree gpg-sign

Name

ostree-gpg-sign — Sign a commit

Synopsis

ostree gpg-sign [OPTIONS...] {COMMIT} {KEY-ID...}

Description

+ Add a new signature to a commit for each specified GPG key. + + Note that currently, this will append a new signature even if + the commit is already signed with a given key. +

Options

--delete

+ Delete signatures having any of the GPG KEY-IDs. +

--gpg-homedir="HOMEDIR"

+ GPG Homedir to use when looking for keyrings. +

diff --git a/man/ostree-init.html b/man/ostree-init.html new file mode 100644 index 0000000000..ae1a7bd4bc --- /dev/null +++ b/man/ostree-init.html @@ -0,0 +1,33 @@ +ostree init

Name

ostree-init — Initialize a new empty repository

Synopsis

ostree init [OPTIONS...]

Description

+ Creates a new empty repository. +

Options

--mode="MODE"

+ Initialize repository in given mode + (bare, bare-user, + bare-user-only, archive). + The default is bare. Note that for + archive the repository configuration file + will actually have archive-z2, as that's + the historical name.

See the manual for differences between these modes. + Briefly, bare mode stores files as they + are, so they can be directly hardlinked, + bare-user uses extended attributes to + store ownership and xattr information, allowing non-root + operations, bare-user-only does not store + ownership information, and archive stores + files compressed, to be served over the network. +

--collection-id=COLLECTION-ID

+ Set the collection ID of the repository. Remotes in clones + of this repository must configure the same value in order to + pull refs which originated in this repository over peer to + peer.

This collection ID must be persistent and globally + unique. It is formatted as a reverse DNS name (like a D-Bus + interface). It must be set to a reverse DNS domain under your + control.

This option may be omitted (the default) to leave + peer to peer distribution unsupported for the repository. A + collection ID may be added to an existing repository in + future to enable peer to peer distribution from that point + onwards.

If the collection ID is changed for the repository + in future, peer to peer distribution of refs from the + repository will break for all peers who do not update their + remote configuration to the new collection ID. +

diff --git a/man/ostree-log.html b/man/ostree-log.html new file mode 100644 index 0000000000..b185ef8aa0 --- /dev/null +++ b/man/ostree-log.html @@ -0,0 +1,13 @@ +ostree log

Name

ostree-log — Show log starting at a commit or ref

Synopsis

ostree log [OPTIONS...] {REF}

Description

+ Shows a log of commits to a given ref or branch. Includes commit checksum, timestamp, and commit message. +

Options

--raw

+ Show raw variant data. +

Example

$ ostree log my-branch

+        commit 67e382b11d213a402a5313e61cbc69dfd5ab93cb07fbb8b71c2e84f79fa5d7dc
+        Date:  2014-06-12 13:42:54 +0000
+            This is the second commit
+
+        commit ce19c41036cc45e49b0cecf6b157523c2105c4de1ce30101def1f759daafcc3e
+        Date:  2014-06-12 11:20:08 +0000
+            Initial commit
+
diff --git a/man/ostree-ls.html b/man/ostree-ls.html new file mode 100644 index 0000000000..b0f9d4cac8 --- /dev/null +++ b/man/ostree-ls.html @@ -0,0 +1,17 @@ +ostree ls

Name

ostree-ls — List file paths

Synopsis

ostree ls [OPTIONS...] {COMMIT} [PATHS...]

Description

+ Prints a list of file paths within the given commit, and within the given path(s) if specified. The first letter of the file line output specifies the type: "-" for regular file, "d" for directory, "l" for symbolic link. See EXAMPLE section for more detail on the specific output. +

Options

--dironly,-d

+ Do not recurse into directory arguments. +

--recursive,-R

+ Print directories recursively. +

--checksum,-C

+ Print checksum. +

--xattrs,-X

+ Print extended attributes. +

--nul-filenames-only

+ Print only filenames, NUL separated. +

Example

$ ostree ls my-branch

+        d00644 0 0    0 /
+        -00644 0 0    2 /helloworld.txt
+        d00755 0 0    0 /testdirectory
+

Here, the first column is the file-type symbol (as explained in the DESCRIPTION section) followed by the S_IFMT file type. The next two columns (here: 0 0) are respectively the user ID and group ID for the file. After the break, the next number represents that file's standard size. The final column is the file path.

diff --git a/man/ostree-prepare-root.html b/man/ostree-prepare-root.html new file mode 100644 index 0000000000..c962482572 --- /dev/null +++ b/man/ostree-prepare-root.html @@ -0,0 +1,63 @@ +ostree prepare-root

Name

ostree-prepare-root — Change the view of a mounted root filesystem to an ostree deployment

Synopsis

ostree prepare-root {TARGET}

Description

+ At its core, ostree operates on an existing mounted filesystem. Tooling such + as ostree admin deploy will create a new directory that can be + used as a bootable target. This tool is designed to run in an initramfs and + set up "remapping" mounts as a view into that filesystem. +

+ As of more recently, this tool also has optional support for composefs, which + creates a distinct mount point layered on top of the underlying filesystem. +

+ The most common pattern today is to use systemd in an initramfs. The systemd + unit shipped upstream is ordered in this way: + + After=sysroot.mount and Before=initrd-root-fs.target +

+ When it runs, the mounted filesystem at the provided TARGET (usually /sysroot) + will be changed such that what appears at /sysroot is actually the + "deployment root" - i.e. a particular versioned subdirectory. What was formerly the + "physical root" i.e. the real root of the filesystem will appear as /sysroot/sysroot. +

+ For /var, by default a bind mount is created from the deployment root to /sysroot/var. +

+ A read-only bind mount is created over /sysroot/usr. The immutable bit (see chattr(1)) is set on the deployment + root, so this provides basic protection for filesystem mutation. If the sysroot.readonly + option is enabled, then /sysroot/sysroot is mounted read-only to provide further protection and a writable bind mount for + /sysroot/etc is created. +

+ Finally, when higher level tooling such as systemd performs a switch-root operation, what + was /sysroot becomes / and after the transition into + the real root, the system will be booted into the "deployment", which is a versioned immutable + filesystem tree. The ostree tooling running in the real root thereafter performs further changes + by operating on /sysroot which is now the "physical root". +

Configuration

+ The /usr/lib/ostree/prepare-root.conf (or /etc/ostree/prepare-root.conf) config file is parsed by ostree-prepare-root. This file must + be present in the initramfs. The default dracut module will copy it from the real root if present. +

sysroot.readonly

A boolean value; the default is false unless composefs is enabled. If this is set to true, then the /sysroot mount point is mounted read-only.

etc.transient

A boolean value; the default is false. If this is set to true, then the /etc mount point is mounted transiently i.e. a non-persistent location.

root.transient

A boolean value; the default is false. + If this is set to true, then the / filesystem will be a writable overlayfs, + with the upper directory being a hidden directory (in the underlying system root filesystem) that will persist across reboots by default. + However, changes will be discarded on OS updates! +

+ Enabling this option can be very useful for cases such as packages (dpkg/rpm/etc) that write content into /opt, + particularly where they expect the target to be writable at runtime. To make that work, ensure that your /opt + directory is *not* a symlink to /var/opt, but is just an empty directory. +

+ Note the /usr mount point remains read-only by default. This option is independent of etc.transient and sysroot.readonly; + it is supported for example to have root.transient=true but etc.transient=false in which case changes to /etc continue + to persist across updates, with the default OSTree 3-way merge applied. +

composefs.enabled

This can be yes, no. maybe or + signed. The default is maybe. If set to yes or + signed, then composefs is always used, and the boot fails if it is not + available. Additionally if set to signed, boot will fail if the image cannot be + validated by a public key. If set to maybe, then composefs is used if supported. +

composefs.keypath

Path to a file with Ed25519 public keys in the initramfs, used if + composefs.enabled is set to signed. The default value for this is + /etc/ostree/initramfs-root-binding.key. For a valid signed boot the target OSTree + commit must be signed by at least one public key in this file, and the commitfs digest listed in the + commit must match the target composefs image.

systemd

+ As mentioned above, this tool comes with a systemd unit file ostree-prepare-root.service + and it is primarily expected to be invoked this way. +

Composefs

+ The default for ostree is to create a plain hardlinked filesystem tree. + composefs support is currently experimental; see the upstream doc/composefs.md + for more information on using it. +

diff --git a/man/ostree-prune.html b/man/ostree-prune.html new file mode 100644 index 0000000000..9a02bcc6d1 --- /dev/null +++ b/man/ostree-prune.html @@ -0,0 +1,31 @@ +ostree prune

Name

ostree-prune — Search for unreachable objects

Synopsis

ostree prune [OPTIONS...]

Description

+ This searches for unreachable objects in the current repository. If unreachable objects are found, the command delete them to free space. If the --no-prune option is invoked, the command will just print unreachable objects and recommend deleting them. +

Options

--no-prune

+ Only display unreachable objects; don't delete. +

--refs-only

+ Only compute reachability via refs. +

--delete-commit=COMMIT

+ Specify a COMMIT to delete. +

--keep-younger-than=DATE

+ All commits older than DATE will be + pruned. The format of DATE is the same as that + accepted by GNU date utility - for more information + see info date. +

--depth=DEPTH

+ Only traverse DEPTH (integer) parents for each commit (default: -1=infinite). +

--static-deltas-only=DEPTH

+ This option may currently only be used in combination with + --delete-commit. Previous versions of ostree silently accepted + the option without that, and ignored it. However, there are desired use + cases for pruning just static deltas (while retaining the commits), and it's + likely at some point this option will be supported for use cases outside of just + --delete-commit. +

--commit-only

+ Only traverse and delete commit objects. This leaves orphaned meta and + content objects, which can be cleaned up with another prune invocation. + One may want to use this option to cheaply delete multiple commits, + and then clean up with a more expensive prune at the end. +

Example

$ ostree prune

+        Total objects: 25627
+        No unreachable objects
+
diff --git a/man/ostree-pull-local.html b/man/ostree-pull-local.html new file mode 100644 index 0000000000..2d52b523c7 --- /dev/null +++ b/man/ostree-pull-local.html @@ -0,0 +1,15 @@ +ostree pull-local

Name

ostree-pull-local — Copy data from a source repository

Synopsis

ostree pull-local [OPTIONS...] {SOURCE_REPO} [REFS...]

Description

+ Copies data from a given repository; optimized for copies only between repositories on the same system. +

Options

--remote="REMOTE"

+ Add REMOTE to refspec. +

--disable-fsync

+ Do no invoke fsync(). +

--untrusted

+ Do not trust source, verify checksums and don't hardlink into source. +

--disable-verify-bindings

+ Disable verification of commit metadata bindings. +

Example

$ ostree pull-local /ostree/repo

+        Enumerating objects...
+        pull: 25709/25709 scanned, 0 objects copied
+        Writing 5 refs
+
diff --git a/man/ostree-pull.html b/man/ostree-pull.html new file mode 100644 index 0000000000..5fd2dba57e --- /dev/null +++ b/man/ostree-pull.html @@ -0,0 +1,63 @@ +ostree pull

Name

ostree-pull — Download data from a remote repository

Synopsis

ostree pull {REMOTE} [BRANCH]

Options

--commit-metadata-only

+ Fetch only the commit metadata. +

--cache-dir=DIR

+ Use an alternate cache directory in DIR. +

--disable-fsync

+ Do no invoke fsync(). +

--localcache-repo

+ Like git's clone --reference. Reuse the provided + OSTree repo as a local object cache when doing HTTP fetches. + May be specified multiple times. +

--untrusted

+ Do not trust local sources, verify checksums and don't hardlink into source. +

--disable-static-deltas

+ Do not use static deltas. +

--mirror

+ Write refs suitable for a mirror, i.e. refs are stored in the + heads/ directory rather than the + remotes/ directory. This makes the target repo + suitable to be exported for other clients to pull from as an ostree + remote. If no specific refs are specified, all refs will be fetched (the + remote must have a summary file present). +

--subpath=SUBPATH

+ Only pull the provided subpath. +

--depth=DEPTH

+ Traverse DEPTH parents (-1=infinite) (default: 0). +

--network-retries=N

+ Specifies how many times each download should be retried upon error (default: 5) +

--disable-retry-on-network-errors

+ Do not retry when network issues happen, instead fail automatically. (Currently only affects libcurl) +

--low-speed-limit-bytes=N

+ The average transfer speed per second of a transfer during the + time set via 'low-speed-time-seconds' for libcurl to abort + (default: 1000) +

--low-speed-time-seconds=N

+ The time in number seconds that the transfer speed should be + below the 'low-speed-limit-bytes' setting for libcurl to abort + (default: 30) +

--max-outstanding-fetcher-requests=N

+ The max amount of concurrent connections allowed. (default: 8) +

--disable-verify-bindings

+ Disable verification of commit metadata bindings. +

Description

+ Without --mirror, this command will create new refs + under remotes/REMOTE/ directory + for each pulled branch unless they are already created. Such + refs can be then referenced by REMOTE:BRANCH in + ostree subcommands (e.g. ostree log origin:exampleos/x86_64/standard). +

+ This command can retrieve just a specific commit, or go all + the way to performing a full mirror of the remote + repository. If no BRANCH is specified, + all configured branches are retrieved. +

+ A special syntax in the @ character allows + specifying a specific commit to retrieve from a branch. The + use cases for this are somewhat similar to pulling a specific + git tag; one could e.g. script a system upgrade to a known-good + version, rather than the latest from the content provider. +

Example

$ ostree --repo=repo pull --depth=-1 --mirror remote_name

Perform a complete mirror of the remote. (This is + likely most useful if your repository is also + archive mode)

$ ostree --repo=repo pull remote_name exampleos/x86_64/standard

Fetch the most recent commit to exampleos/x86_64/standard.

$ ostree --repo=repo pull remote_name exampleos/x86_64/standard@98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4

Download the specific commit starting with + 98ea6e as if it was the latest commit for + exampleos/x86_64/standard.

diff --git a/man/ostree-refs.html b/man/ostree-refs.html new file mode 100644 index 0000000000..2f51e81efa --- /dev/null +++ b/man/ostree-refs.html @@ -0,0 +1,36 @@ +ostree refs

Name

ostree-refs — List refs

Synopsis

ostree refs [OPTIONS...] [PREFIX]

ostree refs {EXISTING} {--create=NEWREF}

Description

+ Lists all refs available on the host. If specified, PREFIX assigns the refspec prefix; default + prefix is null, which lists all refs. This command can also be used to create or delete refs. +

Options

--list

For historical reasons, refs + without this option will strip the specified prefix + from the output. Normally, one wants to see the full + ref, so providing this option ensures the refs are + printed in full, rather than + truncated.

--create=NEWREF

+ Create a ref pointing to the commit EXISTING. NEWREF must not already exist, and EXISTING + must be an existing commit. More than one ref can point to the same commit. +

--delete

+ Delete refs which match PREFIX, rather than listing them. If you are trying to reclaim space, + you will then need to ostree prune or ostree admin cleanup. +

--revision, -r

+ When listing refs, also print their revisions. The revisions + will be separated by a tab character. +

--alias, -A

+ If used with --create, create an alias. Otherwise just list aliases. +

--collections, -c

+ Enable interactions with refs using the combination of their + collection IDs and ref names. When listing refs, this changes + the output format to include collection IDs, and enables + listing remote mirrored refs.

When creating refs, the refspec value passed to the + --create option is treated as + COLLECTION-ID:REF-NAME and a mirrored ref + is created. (This is an abuse of the refspec syntax.)

When deleting refs, all refs whose collection ID equals + PREFIX are deleted. +

--force

+ When creating NEWREF with + --create, allow an existing ref to be + updated instead of erroring. +

Example

$ ostree refs

+        my-branch
+        gnome-ostree/buildmain/x86_64-runtime
+
diff --git a/man/ostree-remote.html b/man/ostree-remote.html new file mode 100644 index 0000000000..28e4edafef --- /dev/null +++ b/man/ostree-remote.html @@ -0,0 +1,60 @@ +ostree remote

Name

ostree-remote — Control remote repository configuration

Synopsis

ostree remote add [OPTIONS...] {NAME} {URL} [BRANCH...]

ostree remote delete {NAME}

ostree remote show-url {NAME}

ostree remote list [OPTIONS...] {NAME}

ostree remote gpg-import [OPTIONS...] {NAME} [KEY-ID...]

ostree remote gpg-list-keys {NAME}

ostree remote refs {NAME}

ostree remote summary [OPTIONS...] {NAME}

ostree remote add-cookie {NAME} {DOMAIN} {PATH} {COOKIE_NAME} {VALUE}

ostree remote delete-cookie {NAME} {DOMAIN} {PATH} {COOKIE_NAME} {VALUE}

ostree remote list-cookies {NAME}

Description

+ Changes remote repository configurations. The NAME refers to the name of the remote. +

+ The BRANCH arguments to the + add subcommand specifies the configured branches + for the remote. See the branches section in + ostree.repo-config(5) + for more information. +

+ The gpg-import subcommand can associate GPG + keys to a specific remote repository for use when pulling signed + commits from that repository (if GPG verification is enabled). The + gpg-list-keys subcommand can be used to see the + GPG keys currently associated with a remote repository. +

+ The GPG keys to import may be in binary OpenPGP format or ASCII armored. The optional [KEY-ID] list can restrict which keys are imported from a keyring file or input stream. All keys are imported if this list is omitted. If neither --keyring nor --stdin options are given, then keys are imported from the user's personal GPG keyring. +

+ The various cookie related command allow management of a remote specific cookie jar. +

'Add' Options

--set="KEY=VALUE"

+ Set config option KEY=VALUE for remote. +

--if-not-exists

+ Do nothing if the provided remote exists. +

--force

+ Replace the provided remote if it exists. +

--no-gpg-verify

+ Disable GPG verification. +

--gpg-import=FILE

+ Import one or more GPG keys from a file. +

+ Equivalent to + ostree remote gpg-import --keyring=FILE. +

--collection-id=COLLECTION-ID

+ Set the collection ID for the remote to a value provided by + the repository owner, which allows refs from this remote to be + shared peer to peer. +

'List' Options

-u, --show-urls

+ Show remote URLs in list +

'Refs' Options

--revision, -r

+ Also print the revisions for each ref. The revisions will + be separated by a tab character. +

--cache-dir=DIR

+ Use an alternate cache directory in DIR. +

'GPG-Import' Options

-k, --keyring=FILE

+ Import one or more keys from a file. +

+ This option may be repeated to import from multiple files, + but may not be used in combination with + --stdin. +

--stdin

+ Import one or more keys from standard input. +

+ This option may not be used in combination with + --keyring. +

'Summary' Options

--cache-dir=DIR

+ Use an alternate cache directory in DIR. +

--raw

+ Show raw variant data +

Example

$ ostree remote show-url local

+        http://192.168.122.1/repo
+
diff --git a/man/ostree-reset.html b/man/ostree-reset.html new file mode 100644 index 0000000000..a38c2559d4 --- /dev/null +++ b/man/ostree-reset.html @@ -0,0 +1,15 @@ +ostree reset

Name

ostree-reset — Reset a ref to a previous commit

Synopsis

ostree reset {REF} {REF_TO_RESET_TO}

Description

+ Given a commit, this command will reset the ref to a previous specified commit. +

Example

$ ostree log my-branch

+        commit 67e382b11d213a402a5313e61cbc69dfd5ab93cb07
+        Date:  2014-06-12 13:42:54 +0000
+            This is the second commit
+
+        commit ce19c41036cc45e49b0cecf6b157523c2105c4de1c
+        Date:  2014-06-12 11:20:08 +0000
+            Initial commit
+

$ ostree reset my-branch my-branch^

$ ostree log my-branch

+        commit ce19c41036cc45e49b0cecf6b157523c2105c4de1c
+        Date:  2014-06-12 11:20:08 +0000
+            Initial commit
+
diff --git a/man/ostree-rev-parse.html b/man/ostree-rev-parse.html new file mode 100644 index 0000000000..53bd4a2f0e --- /dev/null +++ b/man/ostree-rev-parse.html @@ -0,0 +1,7 @@ +ostree rev-parse

Name

ostree-rev-parse — Output the target of a rev

Synopsis

ostree rev-parse {REV} {PATH}

Options

--single, -S

+ If the repository has exactly one commit, then print it; any other case will result in an error. +

Description

+ Given a REV, outputs the checksum of the latest commit of that revision. +

Example

$ ostree rev-parse my-branch

+        ce19c41036cc45e49b0cecf6b157523c2105c4de1ce30101def1f759daafcc3e
+
diff --git a/man/ostree-show.html b/man/ostree-show.html new file mode 100644 index 0000000000..e1c6a6fbaa --- /dev/null +++ b/man/ostree-show.html @@ -0,0 +1,27 @@ +ostree show

Name

ostree-show — Output a metadata object

Synopsis

ostree show [OPTIONS...] {OBJECT}

Description

+ Given an object, shows the metadata for that object. For a particular revision, it will show the data for the most recent commit to that revision. +

Options

--print-related

+ Show the "related" commits. +

--print-variant-type="TYPE"

+ Memory map OBJECT (in this case a filename) to the GVariant type string. +

--list-metadata-keys

+ List the available metadata keys. +

--print-metadata-key="KEY"

+ Print string value of metadata key. +

--list-detached-metadata-keys

+ List the available detached metadata keys. +

--print-detached-metadata-key="KEY"

+ Print string value of detached metadata key. +

--print-sizes

+ Show the commit size metadata. This in only supported for + commits that contain ostree.sizes + metadata. This can be included when creating commits with + ostree commit --generate-sizes. +

--raw

+ Show raw variant data. +

--gpg-homedir="HOMEDIR"

+ GPG home directory to use when looking for keyrings (if have GPGME - GNU Privacy Guard Made Easy). +

Example

$ ostree show my-branch

+        commit 67e382b11d213a402a5313e61cbc69dfd5ab93cb07
+        Date:  2014-06-12 13:42:54 +0000
+
diff --git a/man/ostree-sign.html b/man/ostree-sign.html new file mode 100644 index 0000000000..59b8d92f9d --- /dev/null +++ b/man/ostree-sign.html @@ -0,0 +1,35 @@ +ostree sign

Name

ostree-sign — Sign a commit

Synopsis

ostree sign [OPTIONS...] {COMMIT} {KEY-ID...}

Description

+ Add a new signature to a commit. + + Note that currently, this will append a new signature even if + the commit is already signed with a given key. +

+ There are several "well-known" system places for `ed25519` trusted and revoked public keys -- expected single base64-encoded key per line. +

Files: +

  • /etc/ostree/trusted.ed25519

  • /etc/ostree/revoked.ed25519

  • /usr/share/ostree/trusted.ed25519

  • /usr/share/ostree/revoked.ed25519

+

Directories containing files with keys: +

  • /etc/ostree/trusted.ed25519.d

  • /etc/ostree/revoked.ed25519.d

  • /usr/share/ostree/trusted.ed25519.d

  • /usr/share/ostree/rvokeded.ed25519.d

+

Options

KEY-ID

+

for ed25519:

+ base64-encoded secret (for signing) or public key (for verifying). +

for dummy:

+ ASCII-string used as secret key and public key. +

+

--verify

+ Verify signatures +

-s, --sign-type

+ Use particular signature mechanism. Currently + available ed25519 and dummy + signature types. + + The default is ed25519 . +

--keys-file

+ Read key(s) from file filename. +

+ Valid for ed25519 signature type. + For ed25519 this file must contain base64-encoded + secret key(s) (for signing) or public key(s) (for verifying) per line. +

--keys-dir

+ Redefine the system path, where to search files and subdirectories with + well-known and revoked keys. +

diff --git a/man/ostree-state-overlay@.service.html b/man/ostree-state-overlay@.service.html new file mode 100644 index 0000000000..d3a86be23b --- /dev/null +++ b/man/ostree-state-overlay@.service.html @@ -0,0 +1,35 @@ +ostree-state-overlay

Name

ostree-state-overlay@.service — Set up state overlays

Synopsis

ostree-state-overlay@.service

Experimental

+ Note this feature is currently considered + experimental. It may not work correctly and some of its + semantics may be subject to change. Positive or negative feedback are both + welcome and may be provided at + https://github.com/ostreedev/ostree/discussions. If using + the feature via rpm-ostree, feedback may also be provided at + https://github.com/coreos/rpm-ostree/issues/233. +

Description

+ In some cases, it's useful to be able to have a directory as part of the + OSTree commit yet still have this directory be writable client-side. One + example is software that ships in /opt. + /opt is its own vendor-namespaced alternate file + hierarchy which may contain both code and state. With state overlays, it's + possible to have the code part baked in the OSTree, but still allowing the + directory to be writable so that state can be kept there. +

+ Since it's writable, nothing prevents sufficiently privileged code to + modify or delete content that comes from the OSTree commit. This is in + sharp contrast with content in /usr, and more + closely matches a package manager-based distro. +

+ Crucially, this state is automatically rebased during upgrades (or more + generally, anytime a different OSTree commit is booted). The semantics + of the rebase are as follows: any state file or directory that modified + OSTree content is deleted, otherwise it is kept and merged onto the new + base content (using overlayfs). This mostly matches the semantics of a + package manager. +

+ To enable this feature, simply instantiate the unit template, using the + target path (in escaped systemd path notation) as the instance name. For + example, to enable it on /opt: +


+$systemctlenable--nowostree-state-overlay@opt.service
+

diff --git a/man/ostree-static-delta.html b/man/ostree-static-delta.html new file mode 100644 index 0000000000..914e0c356a --- /dev/null +++ b/man/ostree-static-delta.html @@ -0,0 +1,68 @@ +ostree static-delta

Name

ostree-static-delta — Manage static delta files

Synopsis

ostree static-delta list

ostree static-delta show

ostree static-delta delete

ostree static-delta generate {--to=REV} [OPTIONS...]

ostree static-delta apply-offline [OPTIONS...] {PATH} [KEY-ID...]

ostree static-delta verify [OPTIONS...] {STATIC-DELTA} [KEY-ID...]

Description

+ List and manipulate static delta files. +

'Generate' Options

--from="REV"

+ Create delta from revision REV. +

--to="REV"

+ Create delta to revision REV. (This option is required.) + The delta is from the parent of REV, unless specified otherwise by --from + or --empty. +

--empty

+ Create delta from scratch. +

--max-usize=SIZE

+ Maximum uncompressed size in megabytes. +

--sign-type=ENGINE

+ Use particular signature engine. Currently + available ed25519 and dummy + signature types. + + The default is ed25519 . +

--sign="KEY-ID"

+ There KEY-ID is: +

for ed25519:

+ base64-encoded secret key for signing. +

for dummy:

+ ASCII-string used as secret key. +

+

'Apply-offline' Options

KEY-ID

+

for ed25519:

+ base64-encoded public key for verifying. +

for dummy:

+ ASCII-string used as public key. +

+

--sign-type=ENGINE

+ Use particular signature engine. Currently + available ed25519 and dummy + signature types. +

--keys-file

+ Read key(s) from file filename. +

+ Valid for ed25519 signature type. + For ed25519 this file must contain base64-encoded + public key(s) per line for verifying. +

--keys-dir

+ Redefine the system path, where to search files and subdirectories with + well-known and revoked keys. +

'Verify' Options

KEY-ID

+

for ed25519:

+ base64-encoded public key for verifying. +

for dummy:

+ ASCII-string used as public key. +

+

--sign-type=ENGINE

+ Use particular signature engine. Currently + available ed25519 and dummy + signature types. + + The default is ed25519 . +

--keys-file

+ Read key(s) from file filename. +

+ Valid for ed25519 signature type. + For ed25519 this file must contain base64-encoded + public key(s) per line for verifying. +

--keys-dir

+ Redefine the system path, where to search files and subdirectories with + well-known and revoked keys. +

Example

$ ostree static-delta

+        (No static deltas)
+
diff --git a/man/ostree-summary.html b/man/ostree-summary.html new file mode 100644 index 0000000000..ef497f7c9b --- /dev/null +++ b/man/ostree-summary.html @@ -0,0 +1,52 @@ +ostree summary

Name

ostree-summary — Regenerate or view the summary metadata file

Synopsis

ostree summary [--gpg-sign=KEYID] [--gpg-homedir=HOMEDIR] [--sign=KEYID] [--sign-type=ENGINE] {--update} [--add-metadata=KEY=VALUE...]

ostree summary { --view | --raw }

Description

+ The summary file is an optional higher + level form of repository metadata that describes the + available branches. It needs to be manually regenerated after + a series of commits. Among other things, this allows atomically + updating multiple commits. +

Options

--update,-u

+ Update the summary file. This option can be combined + with --add-metadata to add metadata + fields to the summary. +

If the repository has a collection ID configured, the + ostree-metadata branch for that collection ID + will also be updated with a new commit containing the given metadata, + which will be signed if the summary file is signed.

--add-metadata,-m=KEY=VALUE

+ Specify an additional metadata field to add to the summary. + It must be in the format + KEY=VALUE + or as two separate arguments. The keys must be namespaced + for your organisation or repository using a dot prefix. The + values must be in GVariant text format. For example, + exampleos.end-of-life "@t 1445385600". + This option can be used multiple times. +

--view,-v

+ View the contents of the summary file in a human readable format. +

--raw

+ View the raw bytes of the summary file. +

--gpg-sign=KEYID

+ GPG Key ID to sign the summary with. +

--gpg-homedir=HOMEDIR

+ GPG Homedir to use when looking for keyrings. +

--sign-type=ENGINE

+ Use particular signature engine. Currently + available ed25519 and dummy + signature types. + + The default is ed25519 . +

--sign="KEY-ID"

+ There KEY-ID is: +

for ed25519:

+ base64-encoded secret key for commit signing. +

for dummy:

+ ASCII-string used as secret key. +

+

Examples

$ ostree summary -u

$ ostree summary -u -m key="'value'"

$ ostree summary -v

+* ostree/1/1/0
+    Latest Commit (4.2 MB):
+      9828ab80f357459b4ab50f0629beab2ae3b67318fc3d161d10a89fae353afa90
+    Timestamp (ostree.commit.timestamp): 2017-11-21T01:41:10-08
+    Version (ostree.commit.version): 1.2.3
+
+Last-Modified (ostree.summary.last-modified): 2018-01-12T22:06:38-08
+
diff --git a/man/ostree.html b/man/ostree.html new file mode 100644 index 0000000000..cf185d5c1d --- /dev/null +++ b/man/ostree.html @@ -0,0 +1,194 @@ +ostree

Name

ostree — Manage multiple bootable versioned filesystem trees

Synopsis

ostree {COMMAND} [OPTIONS...]

Description

+ OSTree is a tool for managing multiple bootable + versioned filesystem trees, or just "tree" for + short. In the OSTree model, operating systems no + longer live in the physical "/" root directory. + Instead, they parallel install to the new toplevel + /ostree directory. Each + installed system gets its own + /ostree/deploy/stateroot + directory. (stateroot is the + newer term for osname). +

+ Unlike rpm or + dpkg, OSTree is only aware of + complete filesystem trees. It has no built-in + knowledge of what components went into creating the + filesystem tree. +

+ It is possible to use OSTree in several modes; the + most basic form is to replicate pre-built trees from + a build server. Usually, these pre-built trees are + derived from packages. You might also be using + OSTree underneath a higher level tool which computes + filesystem trees locally. +

+ It must be emphasized that OSTree only supports + read-only trees. To change to + a different tree (upgrade, downgrade, install + software), a new tree is checked out, and a 3-way + merge of configuration is performed. The currently + running tree is not ever modified; the new tree will + become active on a system reboot. +

+ To see the man page for a command run man ostree COMMAND or man ostree-admin COMMAND +

Options

The following options are understood:

--repo

+ For most commands, a repository is + required. If unspecified, the current + directory is used if it appears to be an + OSTree repository. If it isn't, either + the OSTREE_REPO + environment variable is used, or the + system repository located at + /sysroot/ostree/repo. +

-v, --verbose

+ Produce debug level output. +

--version

+ Print version information, including the features enabled + at compile time, and exit. +

Commands

System administrators will primarily interact + with OSTree via the subcommand ostree + admin.

ostree-admin-cleanup(1)

+ Delete untagged + deployments and repository objects. +

ostree-admin-config-diff(1)

+ See changes to + /etc as compared + to the current default (from + /usr/etc). +

ostree-admin-deploy(1)

+ Takes a particular + commit or revision, and sets it up for + the next boot. +

ostree-admin-init-fs(1)

+ Initialize a root filesystem + in a specified path. +

ostree-admin-instutil(1)

+ Utility functions intended primarily for operating system installation programs +

ostree-admin-os-init(1)

+ Initialize the + deployment location for an operating + system with a specified name. +

ostree-admin-status(1)

+ Show and list the deployments. +

ostree-admin-switch(1)

+ Choose a different ref + to track from the same remote as the + current tree. +

ostree-admin-undeploy(1)

+ Remove the previously + INDEX + deployed tree from the bootloader + configuration. +

ostree-admin-upgrade(1)

+ Download the latest version for the + current ref, and deploy it. +

Both administrators and operating system + builders may interact with OSTree via the regular + filesystem manipulation commands. +

ostree-cat(1)

+ Concatenate contents of files +

ostree-checkout(1)

+ Check out a commit into a filesystem tree. +

ostree-checksum(1)

+ Gives checksum of any file. +

ostree-commit(1)

+ Given one or more + trees, create a new commit using those contents. +

ostree-config(1)

+ Change settings. +

ostree-create-usb(1)

+ Put the given refs on an external drive for P2P distribution. +

ostree-diff(1)

+ Concisely list + differences between the given refs. +

ostree-find-remotes(1)

+ Find remotes to serve the given refs. +

ostree-fsck(1)

+ Check a repository for consistency. +

ostree-init(1)

+ Initialize a new repository. +

ostree-log(1)

+ Show revision log. +

ostree-ls(1)

+ List the contents of a given commit. +

ostree-prune(1)

+ Search for unreachable objects. +

ostree-pull-local(1)

+ Copy data from source-repo. +

ostree-pull(1)

+ Download data from remote repo. If you have libsoup. +

ostree-refs(1)

+ List refs. +

ostree-remote(1)

+ Manipulate remote archive configuration. +

ostree-reset(1)

+ Reset a ref to a previous commit. +

ostree-rev-parse(1)

+ Show the SHA256 corresponding to a given rev. +

ostree-show(1)

+ Given an OSTree SHA256 checksum, display its contents. +

ostree-static-delta(1)

+ Manage static delta files. +

ostree-summary(1)

+ Regenerate the repository summary metadata. +

Examples

+ For specific examples, please see the man page regarding the specific ostree command. For example: +

+ man ostree init or man ostree-admin status +

GPG verification

+ OSTree supports signing commits with GPG. Operations on the system + repository by default use keyring files in + /usr/share/ostree/trusted.gpg.d. Any + public key in a keyring file in that directory will be + trusted by the client. No private keys should be present + in this directory. +

+ In addition to the system repository, OSTree supports two + other paths. First, there is a + gpgkeypath option for remotes, which must point + to the filename of an ASCII-armored GPG key, or a directory containing + ASCII-armored GPG keys to import. Multiple file and directory paths + to import from can be specified, as a comma-separated list of paths. This option + may be specified by using --set in ostree remote add. +

+ Second, there is support for a per-remote + remotename.trustedkeys.gpg + file stored in the toplevel of the repository (alongside + objects/ and such). This is + particularly useful when downloading content that may not + be fully trusted (e.g. you want to inspect it but not + deploy it as an OS), or use it for containers. This file + is written via ostree remote add + --gpg-import. +

Terminology

+ The following terms are commonly used throughout the man pages. Terms in upper case letters + are literals used in command line arguments. +

BRANCH

+ Branch name. Part of a REF. +

CHECKSUM

+ A SHA256 hash of a object stored in the OSTree repository. This can be a content, + a dirtree, a dirmeta or a commit object. If the SHA256 hash of a commit object is + meant, the term COMMIT is used. +

COMMIT

+ A SHA256 hash of a commit object. +

REF

+ A reference to a particular commit. References are text files stored in + refs/ that name (refer to) a particular commit. A + reference can only be the branch name part, in which case a local reference + is used (e.g. mybranch/stable). If a remote branch + is referred to, the remote name followed by a colon and the branch name + needs to be used (e.g. myremote:mybranch/stable). +

REV, REFSPEC

+ A specific revision, a commit. This can be anything which can be resolved to a + commit, e.g. a REF or a + COMMIT. +

SHA256

+ A cryptographic hash function used to store objects in the OSTree + repository. The hashes have a length of 256 bites and are typically + shown and passed to ostree in its 64 ASCII character long hexadecimal + representation + (e.g. 0fc70ed33cfd7d26fe99ae29afb7682ddd0e2157a4898bd8cfcdc8a03565b870). +

See Also

+ ostree.repo(5) +

diff --git a/man/ostree.repo-config.html b/man/ostree.repo-config.html new file mode 100644 index 0000000000..adf7690d0a --- /dev/null +++ b/man/ostree.repo-config.html @@ -0,0 +1,219 @@ +ostree.repo-config

Name

ostree.repo-config — OSTree repository configuration

Description

+ The config file in an OSTree + repository is a "keyfile" in the XDG + Desktop Entry Specification format. It has + several global flags, as well as zero or more remote + entries which describe how to access remote + repositories. +

+ See ostree.repo(5) for more information + about OSTree repositories. +

[core] Section Options

+ Repository-global options. The following entries are defined: +

mode

One of bare, bare-user, bare-user-only, or archive-z2 (note that archive is used everywhere else.)

repo_version

Currently, this must be set to 1.

auto-update-summary

Boolean value controlling whether or not to + automatically update the summary file after any ref is added, + removed, or updated. Other modifications which may render a + summary file stale (like static deltas, or collection IDs) do + not currently trigger an auto-update. +

commit-update-summary

This option is deprecated. Use + auto-update-summary instead, for which this + option is now an alias.

fsync

Boolean value controlling whether or not to + ensure files are on stable storage when performing operations + such as commits, pulls, and checkouts. Defaults to + true.

+ If you disable fsync, OSTree will no longer be robust + against kernel crashes or power loss. +

+ You might choose to disable this for local development + repositories, under the assumption they can be recreated from + source. Similarly, you could disable for a mirror where you could + re-pull. +

+ For the system repository, you might choose to disable fsync + if you have uninterruptable power supplies and a well tested + kernel. +

per-object-fsync

By default, OSTree will batch fsync() after + writing everything; however, this can cause latency spikes + for other processes which are also invoking fsync(). + Turn on this boolean to reduce potential latency spikes, + at the cost of slowing down OSTree updates. You most + likely want this on by default for "background" OS updates. +

min-free-space-percent

+ Integer percentage value (0-99) that specifies a minimum percentage + of total space (in blocks) in the underlying filesystem to keep + free. The default value is 3, which is enforced when neither this + option nor min-free-space-size are set. +

+ If min-free-space-size is set to a non-zero + value, min-free-space-percent is ignored. Note + that, min-free-space-percent is not enforced on + metadata objects. It is assumed that metadata objects are relatively + small in size compared to content objects and thus kept outside the + scope of this option. +

min-free-space-size

+ Value (in power-of-2 MB, GB or TB) that specifies a minimum space + in the underlying filesystem to keep free. Examples of acceptable + values: 500MB (524288000 bytes), + 1GB (1073741824 bytes), + 1TB (1099511627776 bytes). +

+ If this option is set to a non-zero value, and + min-free-space-percent is also set, this option + takes priority. Note that, min-free-space-size is + not enforced on metadata objects. It is assumed that metadata objects + are relatively small in size compared to content objects and thus kept + outside the scope of this option. +

add-remotes-config-dir

+ Boolean value controlling whether new remotes will be added + in the remotes configuration directory. Defaults to + true for system ostree repositories. When + this is false, remotes will be added in + the repository's config file. +

+ This only applies to repositories that use a remotes + configuration directory such as system ostree repositories, + which use /etc/ostree/remotes.d. + Non-system repositories do not use a remotes configuration + directory unless one is specified when the repository is + opened. +

payload-link-threshold

An integer value that specifies a minimum file size for creating + a payload link. By default it is disabled. +

collection-id

A reverse DNS domain name under your control, which enables peer + to peer distribution of refs in this repository. See the + --collection-id section in + ostree-init(1) +

locking

Boolean value controlling whether or not OSTree does + repository locking internally. This uses file locks and is + hence for multiple process exclusion (e.g. Flatpak and OSTree + writing to the same repository separately). This is enabled by + default since 2018.5. +

lock-timeout-secs

Integer value controlling the number of seconds to + block while attempting to acquire a lock (see above). A value + of -1 means block indefinitely. The default value is 300. This timeout + is now regarded as a mistake; because it's likely to cause flakes. + It's recommended to set it to -1, and have timeouts at a higher application + level if desired. +

default-repo-finders

Semicolon separated default list of finders (sources + for refs) to use when pulling. This can be used to disable + pulling from mounted filesystems, peers on the local network, + or the Internet. However note that it only applies when a set + of finders isn't explicitly specified, either by a consumer of + libostree API or on the command line. Possible values: + config, lan, and + mount (or any combination thereof). If unset, this + defaults to config;mount; (since the LAN finder is + costly). +

no-deltas-in-summary

Boolean value controlling whether OSTree should skip + putting an index of available deltas in the summary file. Defaults to false. +

+ Since 2020.7 OSTree can use delta indexes outside the summary file, + making the summary file smaller (especially for larger repositories). However + by default we still create the index in the summary file to make older clients + work. If you know all clients will be 2020.7 later you can enable this to + save network bandwidth. +

[remote "name"] Section Options

+ Describes a remote repository location. +

url

Must be present; declares URL for accessing metadata and + content for remote. See also contenturl. The + supported schemes are documented below.

contenturl

Declares URL for accessing content (filez, static delta + parts). When specified, url is used just for + metadata: summary, static delta "superblocks".

branches

A list of strings. Represents the default configured + branches to fetch from the remote when no specific branches are + requested during a pull operation.

proxy

A string value, if given should be a URL for a + HTTP proxy to use for access to this repository.

gpg-verify

A boolean value, defaults to true. + Controls whether or not OSTree will require commits to be + signed by a known GPG key. For more information, see the + ostree(1) + manual under GPG.

gpg-verify-summary

A boolean value, defaults to false. + Controls whether or not OSTree will check if the summary + is signed by a known GPG key. + For more information, see the ostree(1) + manual under GPG.

tls-permissive

A boolean value, defaults to false. By + default, server TLS certificates will be checked against the + system certificate store. If this variable is set, any + certificate will be accepted.

tls-client-cert-path

Path to file for client-side certificate, to present when making requests to this repository.

tls-client-key-path

Path to file containing client-side certificate key, to present when making requests to this repository.

tls-ca-path

Path to file containing trusted anchors instead of the system CA database.

http2

A boolean value, defaults to true. By + default, libostree will use HTTP2; setting this to false + will disable it. May be useful to work around broken servers. +

unconfigured-state

If set, pulls from this remote will fail with the configured text. This is intended for OS vendors which have a subscription process to access content.

custom-backend

If set, pulls from this remote via libostree will fail with an error that mentions the value. + It is recommended to make this a software identifier token (e.g. "examplecorp-fetcher"), not freeform text ("ExampleCorp Fetcher"). + This is intended to be used by higher level software that wants to fetch ostree commits via some other mechanism, while still reusing the core libostree infrastructure around e.g. signatures. +

[sysroot] Section Options

+ Options for the sysroot, which contains the OSTree repository, + deployments, and stateroots. The following entries are defined: +

readonly

A boolean value. If this is set to true, then the + /sysroot mount point is mounted read-only. This is configured a + legacy repository configuration and the equivalent option in ostree/prepare-root.conf + should be used instead - see ostree-prepare-root(1). +

bootloader

Configure the bootloader that OSTree uses when + deploying the sysroot. This may take the values + bootloader=none, bootloader=auto, + bootloader=grub2, bootloader=syslinux, + bootloader=uboot or bootloader=zipl. + Default is auto. +

+ If none, then OSTree will generate only BLS (Boot + Loader Specification) fragments in sysroot/boot/loader/entries/ + for the deployment. +

+ If auto, then in addition to generating BLS + fragments, OSTree will dynamically check for the existence of grub2, + uboot, and syslinux bootloaders. If one of the bootloaders is found, + then OSTree will generate a config for the bootloader found. For + example, grub2-mkconfig is run for the grub2 case. +

+ A specific bootloader type may also be explicitly requested by choosing + grub2, syslinux, uboot or + zipl. +

bls-append-except-default

A semicolon separated string list of key-value pairs. For example: + bls-append-except-default=key1=value1;key2=value2. These key-value + pairs will be injected into the generated BLS fragments of the non-default deployments. + In other words, the BLS fragment of the default deployment will be unaffected by + bls-append-except-default. +

bootprefix

A boolean value; defaults to false. If set to true, the bootloader entries + generated will include /boot as a prefix. This will likely be turned + on by default in the future. +

[ex-integrity] Section Options

+ The "ex-" prefix here signifies experimental options. The ex-integrity section + contains options related to system integrity. Information about experimental + options is canonically found in upstream tracking issues. +

/etc/ostree/remotes.d

+ In addition to the /ostree/repo/config + file, remotes may also be specified in + /etc/ostree/remotes.d. The remote + configuration file must end in .conf; files + whose name does not end in .conf will be + ignored. +

Repository url/contenturl

+ Originally, OSTree had just a url option + for remotes. Since then, the contenturl + option was introduced. Both of these support + file, http, and + https schemes. +

+ Additionally, both of these can be prefixed with the string + mirrorlist=, which instructs the client + that the target url is a "mirrorlist" format, which is + a plain text file of newline-separated URLs. Earlier + URLs will be given precedence. +

+ Note that currently, the tls-ca-path and + tls-client-cert-path options apply to every HTTP + request, even when contenturl and/or + mirrorlist are in use. This may change in the future to + only apply to metadata (i.e. url, not + contenturl) fetches. +

Per-remote GPG keyrings and verification

+ OSTree supports a per-remote GPG keyring, as well as a + gpgkeypath option. For more information see + ostree(1). + in the section GPG verification. +

Per-remote HTTP cookies

+ Some content providers may want to control access to remote + repositories via HTTP cookies. The ostree remote + add-cookie and ostree remote + delete-cookie commands will update a per-remote + lookaside cookie jar, named + $remotename.cookies.txt. +

See Also

+ ostree(1), ostree.repo(5) +

diff --git a/man/ostree.repo.html b/man/ostree.repo.html new file mode 100644 index 0000000000..5cf18a6835 --- /dev/null +++ b/man/ostree.repo.html @@ -0,0 +1,30 @@ +ostree.repo

Name

ostree.repo — OSTree repository configuration and layout

Description

+ An OSTree repository is structurally similar to a + git repository; it is a content-addressed object + store containing filesystem trees. However, unlike + git, ostree is designed to store operating system + binaries. It records the Unix uid and gid, + permissions, as well as extended attributes. +

+ A repository can be in one of three modes; + bare, which is designed as a hard + link source for operating system checkouts, + bare-user, which is like + bare but works on systems that + run as non-root as well as non-root containers, and + archive-z2, which is designed for + static HTTP servers. +

+ There is a system repository located at + /ostree/repo. If no repository + is specified -- either by a command-line option or the + OSTREE_REPO environment variable -- + the ostree as well as many API + calls will use it by default. +

Components of a repository

+ The only user-editable component is the + config file. For more + information, see ostree.repo-config(5). +

diff --git a/man/rofiles-fuse.html b/man/rofiles-fuse.html new file mode 100644 index 0000000000..b9b46ace03 --- /dev/null +++ b/man/rofiles-fuse.html @@ -0,0 +1,31 @@ +rofiles-fuse

Name

rofiles-fuse — Use FUSE to create a view where directories are writable, files are immutable

Synopsis

rofiles-fuse SRCDIR MNTPOINT

Description

+ Creating a checkout from an OSTree repository by default + uses hard links, which means an in-place mutation to any + file corrupts the repository and all checkouts. This can be + problematic if one wishes to run arbitrary programs against + such a checkout. For example, RPM %post + scripts or equivalent. +

+ In the case where one wants to create a tree commit derived + from other content, using rofiles-fuse in + concert with ostree commit + --link-checkout-speedup (or the underlying API) + can ensure that only new files are checksummed. +

Example: Update an OSTree commit

+# Initialize a checkout and mount
+$ ostree --repo=repo checkout somebranch branch-checkout
+$ mkdir mnt
+$ rofiles-fuse branch-checkout mnt
+
+# Now, arbitrary changes to mnt/ are reflected in branch-checkout
+$ echo somenewcontent > mnt/anewfile
+$ mkdir mnt/anewdir
+$ rm mnt/someoriginalcontent -rf
+
+# Commit and cleanup
+$ fusermount -u mnt
+$ ostree --repo=repo commit --link-checkout-speedup -b somebranch -s 'Commit new content' --tree=dir=branch-checkout
+$ rm mnt branch-checkout -rf
+	

See Also

+ ostree(1) +

diff --git a/reference/home.png b/reference/home.png new file mode 100644 index 0000000000..9346b336a7 Binary files /dev/null and b/reference/home.png differ diff --git a/reference/index.html b/reference/index.html new file mode 100644 index 0000000000..bd623aab1a --- /dev/null +++ b/reference/index.html @@ -0,0 +1,97 @@ + + + + +OSTree API references: OSTree API references + + + + + + + +
+
+
+
+

for OSTree 2024.6

+
+
+
+
+
API Reference
+
+
+Core repository-independent functions — Create, validate, and convert core data types +
+
+OstreeRepo: Content-addressed object store — A git-like storage system for operating system binaries +
+
+In-memory modifiable filesystem tree — Modifiable filesystem tree +
+
+Root partition mount point — Manage physical root filesystem +
+
+Progress notification system for asynchronous operations — Values representing progress +
+
+SELinux policy management — Read SELinux policy and manage filesystem labels +
+
+Simple upgrade class — Upgrade OSTree systems +
+
+GPG signature verification results — Inspect detached GPG signatures +
+
+Signature management — Sign and verify commits +
+
+ostree-bootconfig-parser +
+
+ostree-chain-input-stream +
+
+ostree-checksum-input-stream +
+
+ostree-content-writer +
+
+ostree-deployment +
+
+ostree-diff +
+
+ostree-kernel-args +
+
+ostree-ref +
+
+ostree-remote +
+
+ostree-repo-file +
+
+ostree-repo-finder +
+
+ostree-repo-remote-finder +
+
+ostree-version — ostree version checking +
+
API Index
+
+
+
+ + + \ No newline at end of file diff --git a/reference/left-insensitive.png b/reference/left-insensitive.png new file mode 100644 index 0000000000..3269393a7f Binary files /dev/null and b/reference/left-insensitive.png differ diff --git a/reference/left.png b/reference/left.png new file mode 100644 index 0000000000..2abde032b0 Binary files /dev/null and b/reference/left.png differ diff --git a/reference/ostree-Core-repository-independent-functions.html b/reference/ostree-Core-repository-independent-functions.html new file mode 100644 index 0000000000..ec7684fdcc --- /dev/null +++ b/reference/ostree-Core-repository-independent-functions.html @@ -0,0 +1,3058 @@ + + + + +Core repository-independent functions: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

Core repository-independent functions

+

Core repository-independent functions — Create, validate, and convert core data types

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
#define +OSTREE_OBJECT_TYPE_IS_META() +
const GVariantType * + +ostree_metadata_variant_type () +
+gboolean + +ostree_validate_checksum_string () +
+gboolean + +ostree_validate_collection_id () +
+guchar * + +ostree_checksum_to_bytes () +
+GVariant * + +ostree_checksum_to_bytes_v () +
+char * + +ostree_checksum_from_bytes () +
+char * + +ostree_checksum_from_bytes_v () +
+void + +ostree_checksum_inplace_from_bytes () +
+void + +ostree_checksum_inplace_to_bytes () +
const guchar * + +ostree_checksum_bytes_peek () +
const guchar * + +ostree_checksum_bytes_peek_validate () +
+char * + +ostree_checksum_b64_from_bytes () +
+guchar * + +ostree_checksum_b64_to_bytes () +
+void + +ostree_checksum_b64_inplace_from_bytes () +
+void + +ostree_checksum_b64_inplace_to_bytes () +
+int + +ostree_cmp_checksum_bytes () +
+gboolean + +ostree_validate_rev () +
+gboolean + +ostree_validate_remote_name () +
+gboolean + +ostree_parse_refspec () +
const char * + +ostree_object_type_to_string () +
+OstreeObjectType + +ostree_object_type_from_string () +
+guint + +ostree_hash_object_name () +
+GVariant * + +ostree_object_name_serialize () +
+void + +ostree_object_name_deserialize () +
+char * + +ostree_object_to_string () +
+void + +ostree_object_from_string () +
+gboolean + +ostree_content_stream_parse () +
+gboolean + +ostree_content_file_parse () +
+gboolean + +ostree_content_file_parse_at () +
+gboolean + +ostree_raw_file_to_archive_z2_stream () +
+gboolean + +ostree_raw_file_to_archive_z2_stream_with_options () +
+gboolean + +ostree_raw_file_to_content_stream () +
+gboolean + +ostree_break_hardlink () +
+gboolean + +ostree_checksum_file_from_input () +
+gboolean + +ostree_checksum_file () +
+gboolean + +ostree_checksum_file_at () +
+void + +ostree_checksum_file_async () +
+gboolean + +ostree_checksum_file_async_finish () +
+GVariant * + +ostree_fs_get_all_xattrs () +
+GVariant * + +ostree_fs_get_all_xattrs_at () +
+GVariant * + +ostree_create_directory_metadata () +
+gboolean + +ostree_validate_structureof_objtype () +
+gboolean + +ostree_validate_structureof_csum_v () +
+gboolean + +ostree_validate_structureof_checksum_string () +
+gboolean + +ostree_validate_structureof_file_mode () +
+gboolean + +ostree_validate_structureof_commit () +
+gboolean + +ostree_validate_structureof_dirtree () +
+gboolean + +ostree_validate_structureof_dirmeta () +
+gchar * + +ostree_commit_get_parent () +
+guint64 + +ostree_commit_get_timestamp () +
+gboolean + +ostree_commit_metadata_for_bootable () +
+gchar * + +ostree_commit_get_content_checksum () +
+gboolean + +ostree_commit_get_object_sizes () +
+OstreeCommitSizesEntry * + +ostree_commit_sizes_entry_new () +
+OstreeCommitSizesEntry * + +ostree_commit_sizes_entry_copy () +
+void + +ostree_commit_sizes_entry_free () +
+gboolean + +ostree_check_version () +
+
+ +
+

Description

+

These functions implement repository-independent algorithms for +operating on the core OSTree data formats, such as converting +GFileInfo into a GVariant.

+

There are 4 types of objects; file, dirmeta, tree, and commit. The +last 3 are metadata, and the file object is the only content object +type.

+

All metadata objects are stored as GVariant (big endian). The +rationale for this is the same as that of the ext{2,3,4} family of +filesystems; most developers will be using LE, and so it's better +to continually test the BE->LE swap.

+

The file object is a custom format in order to support streaming.

+
+
+

Functions

+
+

OSTREE_OBJECT_TYPE_IS_META()

+
#define OSTREE_OBJECT_TYPE_IS_META(t) (t >= 2 && t <= 6)
+
+
+

Parameters

+
+++++ + + + + + +

t

An OstreeObjectType

 
+
+
+

Returns

+

TRUE if object type is metadata

+
+
+
+
+

ostree_metadata_variant_type ()

+
const GVariantType *
+ostree_metadata_variant_type (OstreeObjectType objtype);
+
+
+
+

ostree_validate_checksum_string ()

+
gboolean
+ostree_validate_checksum_string (const char *sha256,
+                                 GError **error);
+

Use this function to see if input strings are checksums.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

sha256

SHA256 hex string

 

error

Error

 
+
+
+

Returns

+

TRUE if sha256 +is a valid checksum string, FALSE otherwise

+
+
+
+
+

ostree_validate_collection_id ()

+
gboolean
+ostree_validate_collection_id (const char *collection_id,
+                               GError **error);
+

Check whether the given collection_id + is valid. Return an error if it is +invalid or NULL.

+

Valid collection IDs are reverse DNS names:

+
    +
  • They are composed of 1 or more elements separated by a period (.) character. +All elements must contain at least one character.

  • +
  • Each element must only contain the ASCII characters [A-Z][a-z][0-9]_ and must not +begin with a digit.

  • +
  • They must contain at least one . (period) character (and thus at least two elements).

  • +
  • They must not begin with a . (period) character.

  • +
  • They must not exceed 255 characters in length.

  • +
+

(This makes their format identical to D-Bus interface names, for consistency.)

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

collection_id

A collection ID.

[nullable]

error

Error

 
+
+
+

Returns

+

TRUE if collection_id +is a valid collection ID, FALSE if it is invalid +or NULL

+
+

Since: 2018.6

+
+
+
+

ostree_checksum_to_bytes ()

+
guchar *
+ostree_checksum_to_bytes (const char *checksum);
+
+

Parameters

+
+++++ + + + + + +

checksum

An ASCII checksum

 
+
+
+

Returns

+

Binary checksum from checksum +of length 32; +free with g_free().

+

[transfer full][array fixed-size=32]

+
+
+
+
+

ostree_checksum_to_bytes_v ()

+
GVariant *
+ostree_checksum_to_bytes_v (const char *checksum);
+
+

Parameters

+
+++++ + + + + + +

checksum

An ASCII checksum

 
+
+
+

Returns

+

New GVariant of type ay with length 32.

+

[transfer full]

+
+
+
+
+

ostree_checksum_from_bytes ()

+
char *
+ostree_checksum_from_bytes (const guchar *csum);
+
+

Parameters

+
+++++ + + + + + +

csum

An binary checksum of length 32.

[array fixed-size=32]
+
+
+

Returns

+

String form of csum +.

+

[transfer full]

+
+
+
+
+

ostree_checksum_from_bytes_v ()

+
char *
+ostree_checksum_from_bytes_v (GVariant *csum_v);
+
+

Parameters

+
+++++ + + + + + +

csum_v

GVariant of type ay

 
+
+
+

Returns

+

String form of csum_bytes +.

+

[transfer full]

+
+
+
+
+

ostree_checksum_inplace_from_bytes ()

+
void
+ostree_checksum_inplace_from_bytes (const guchar *csum,
+                                    char *buf);
+

Overwrite the contents of buf + with stringified version of csum +.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

csum

An binary checksum of length 32.

[array fixed-size=32]

buf

Output location, must be at least OSTREE_SHA256_STRING_LEN+1 bytes in length

 
+
+
+
+
+

ostree_checksum_inplace_to_bytes ()

+
void
+ostree_checksum_inplace_to_bytes (const char *checksum,
+                                  guchar *buf);
+

Convert checksum + from a string to binary in-place, without +allocating memory. Use this function in hot code paths.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

checksum

a SHA256 string

 

buf

Output buffer with at least 32 bytes of space

 
+
+
+
+
+

ostree_checksum_bytes_peek ()

+
const guchar *
+ostree_checksum_bytes_peek (GVariant *bytes);
+
+

Parameters

+
+++++ + + + + + +

bytes

GVariant of type ay

 
+
+
+

Returns

+

Binary checksum data in +bytes +; do not free. If bytes +does not have the correct length, return NULL.

+

[transfer none][array fixed-size=32][element-type guint8]

+
+
+
+
+

ostree_checksum_bytes_peek_validate ()

+
const guchar *
+ostree_checksum_bytes_peek_validate (GVariant *bytes,
+                                     GError **error);
+

Like ostree_checksum_bytes_peek(), but also throws error +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

bytes

GVariant of type ay

 

error

Errror

 
+
+
+

Returns

+

Binary checksum data.

+

[transfer none][array fixed-size=32][element-type guint8]

+
+
+
+
+

ostree_checksum_b64_from_bytes ()

+
char *
+ostree_checksum_b64_from_bytes (const guchar *csum);
+
+

Parameters

+
+++++ + + + + + +

csum

An binary checksum of length 32.

[array fixed-size=32]
+
+
+

Returns

+

Modified base64 encoding of csum +

+

The "modified" term refers to the fact that instead of '/', the '_' +character is used.

+

[transfer full]

+
+

Since: 2016.8

+
+
+
+

ostree_checksum_b64_to_bytes ()

+
guchar *
+ostree_checksum_b64_to_bytes (const char *checksum);
+
+

Parameters

+
+++++ + + + + + +

checksum

An ASCII checksum

 
+
+
+

Returns

+

Binary version of checksum +.

+

[transfer full][array fixed-size=32]

+
+

Since: 2016.8

+
+
+
+

ostree_checksum_b64_inplace_from_bytes ()

+
void
+ostree_checksum_b64_inplace_from_bytes
+                               (const guchar *csum,
+                                char *buf);
+

Overwrite the contents of buf + with modified base64 encoding of csum +. +The "modified" term refers to the fact that instead of '/', the '_' +character is used.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

csum

An binary checksum of length 32.

[array fixed-size=32]

buf

Output location, must be at least 44 bytes in length

 
+
+
+
+
+

ostree_checksum_b64_inplace_to_bytes ()

+
void
+ostree_checksum_b64_inplace_to_bytes (const char *checksum,
+                                      guint8 *buf);
+

Overwrite the contents of buf + with stringified version of csum +.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

checksum

An binary checksum of length 32.

[array fixed-size=32]

buf

Output location, must be at least 45 bytes in length

 
+
+
+
+
+

ostree_cmp_checksum_bytes ()

+
int
+ostree_cmp_checksum_bytes (const guchar *a,
+                           const guchar *b);
+

Compare two binary checksums, using memcmp().

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

a

A binary checksum

 

b

A binary checksum

 
+
+
+
+
+

ostree_validate_rev ()

+
gboolean
+ostree_validate_rev (const char *rev,
+                     GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

rev

A revision string

 

error

Error

 
+
+
+

Returns

+

TRUE if rev +is a valid ref string

+
+
+
+
+

ostree_validate_remote_name ()

+
gboolean
+ostree_validate_remote_name (const char *remote_name,
+                             GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

remote_name

A remote name

 

error

Error

 
+
+
+

Returns

+

TRUE if remote_name +is a valid remote name

+
+

Since: 2017.8

+
+
+
+

ostree_parse_refspec ()

+
gboolean
+ostree_parse_refspec (const char *refspec,
+                      char **out_remote,
+                      char **out_ref,
+                      GError **error);
+

Split a refspec like gnome-ostree:gnome-ostree/buildmain or just +gnome-ostree/buildmain into two parts. In the first case, out_remote + +will be set to gnome-ostree, and out_ref + to gnome-ostree/buildmain. +In the second case (a local ref), out_remote + will be NULL, and out_ref + +will be gnome-ostree/buildmain. In both cases, TRUE will be returned.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

refspec

A "refspec" string

 

out_remote

Return location for the remote name, +or NULL if the refspec refs to a local ref.

[out][nullable][optional]

out_ref

Return location for the ref name.

[out][not nullable][optional]

error

Error

 
+
+
+

Returns

+

TRUE on successful parsing, FALSE otherwise

+
+
+
+
+

ostree_object_type_to_string ()

+
const char *
+ostree_object_type_to_string (OstreeObjectType objtype);
+

Serialize objtype + to a string; this is used for file extensions.

+
+

Parameters

+
+++++ + + + + + +

objtype

an OstreeObjectType

 
+
+
+
+
+

ostree_object_type_from_string ()

+
OstreeObjectType
+ostree_object_type_from_string (const char *str);
+

The reverse of ostree_object_type_to_string().

+
+

Parameters

+
+++++ + + + + + +

str

A stringified version of OstreeObjectType

 
+
+
+
+
+

ostree_hash_object_name ()

+
guint
+ostree_hash_object_name (gconstpointer a);
+

Use this function with GHashTable and ostree_object_name_serialize().

+
+

Parameters

+
+++++ + + + + + +

a

A GVariant containing a serialized object

 
+
+
+
+
+

ostree_object_name_serialize ()

+
GVariant *
+ostree_object_name_serialize (const char *checksum,
+                              OstreeObjectType objtype);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

checksum

An ASCII checksum

 

objtype

An object type

 
+
+
+

Returns

+

A new floating GVariant containing checksum string and objtype.

+

[transfer floating]

+
+
+
+
+

ostree_object_name_deserialize ()

+
void
+ostree_object_name_deserialize (GVariant *variant,
+                                const char **out_checksum,
+                                OstreeObjectType *out_objtype);
+

Reverse ostree_object_name_serialize(). Note that out_checksum + is +only valid for the lifetime of variant +, and must not be freed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

variant

A GVariant of type (su)

 

out_checksum

Pointer into string memory of variant +with checksum.

[out][transfer none]

out_objtype

Return object type.

[out]
+
+
+
+
+

ostree_object_to_string ()

+
char *
+ostree_object_to_string (const char *checksum,
+                         OstreeObjectType objtype);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

checksum

An ASCII checksum

 

objtype

Object type

 
+
+
+

Returns

+

A string containing both checksum +and a stringifed version of objtype +

+
+
+
+
+

ostree_object_from_string ()

+
void
+ostree_object_from_string (const char *str,
+                           gchar **out_checksum,
+                           OstreeObjectType *out_objtype);
+

Reverse ostree_object_to_string().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

str

An ASCII checksum

 

out_checksum

Parsed checksum.

[out][transfer full]

out_objtype

Parsed object type.

[out]
+
+
+
+
+

ostree_content_stream_parse ()

+
gboolean
+ostree_content_stream_parse (gboolean compressed,
+                             GInputStream *input,
+                             guint64 input_length,
+                             gboolean trusted,
+                             GInputStream **out_input,
+                             GFileInfo **out_file_info,
+                             GVariant **out_xattrs,
+                             GCancellable *cancellable,
+                             GError **error);
+

The reverse of ostree_raw_file_to_content_stream(); this function +converts an object content stream back into components.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

compressed

Whether or not the stream is zlib-compressed

 

input

Object content stream

 

input_length

Length of stream

 

trusted

If TRUE, assume the content has been validated

 

out_input

The raw file content stream.

[out]

out_file_info

Normal metadata.

[out]

out_xattrs

Extended attributes.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_content_file_parse ()

+
gboolean
+ostree_content_file_parse (gboolean compressed,
+                           GFile *content_path,
+                           gboolean trusted,
+                           GInputStream **out_input,
+                           GFileInfo **out_file_info,
+                           GVariant **out_xattrs,
+                           GCancellable *cancellable,
+                           GError **error);
+

A thin wrapper for ostree_content_stream_parse(); this function +converts an object content stream back into components.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

compressed

Whether or not the stream is zlib-compressed

 

content_path

Path to file containing content

 

trusted

If TRUE, assume the content has been validated

 

out_input

The raw file content stream.

[out]

out_file_info

Normal metadata.

[out]

out_xattrs

Extended attributes.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_content_file_parse_at ()

+
gboolean
+ostree_content_file_parse_at (gboolean compressed,
+                              int parent_dfd,
+                              const char *path,
+                              gboolean trusted,
+                              GInputStream **out_input,
+                              GFileInfo **out_file_info,
+                              GVariant **out_xattrs,
+                              GCancellable *cancellable,
+                              GError **error);
+

A thin wrapper for ostree_content_stream_parse(); this function +converts an object content stream back into components.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

compressed

Whether or not the stream is zlib-compressed

 

parent_dfd

Directory file descriptor

 

path

Subpath

 

trusted

If TRUE, assume the content has been validated

 

out_input

The raw file content stream.

[out]

out_file_info

Normal metadata.

[out]

out_xattrs

Extended attributes.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_raw_file_to_archive_z2_stream ()

+
gboolean
+ostree_raw_file_to_archive_z2_stream (GInputStream *input,
+                                      GFileInfo *file_info,
+                                      GVariant *xattrs,
+                                      GInputStream **out_input,
+                                      GCancellable *cancellable,
+                                      GError **error);
+

Convert from a "bare" file representation into an +OSTREE_OBJECT_TYPE_FILE stream suitable for ostree pull.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

input

File raw content stream

 

file_info

A file info

 

xattrs

Optional extended attributes.

[allow-none]

out_input

Serialized object stream.

[out]

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2016.6

+
+
+
+

ostree_raw_file_to_archive_z2_stream_with_options ()

+
gboolean
+ostree_raw_file_to_archive_z2_stream_with_options
+                               (GInputStream *input,
+                                GFileInfo *file_info,
+                                GVariant *xattrs,
+                                GVariant *options,
+                                GInputStream **out_input,
+                                GCancellable *cancellable,
+                                GError **error);
+

Like ostree_raw_file_to_archive_z2_stream(), but supports an extensible set +of flags. The following flags are currently defined:

+
  • compression-level (i): Level of compression to use, 0–9, with 0 being +the least compression, and <0 giving the default level (currently 6).

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

input

File raw content stream

 

file_info

A file info

 

xattrs

Optional extended attributes.

[allow-none]

options

A GVariant a{sv} with an extensible set of flags.

[nullable]

out_input

Serialized object stream.

[out]

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2017.3

+
+
+
+

ostree_raw_file_to_content_stream ()

+
gboolean
+ostree_raw_file_to_content_stream (GInputStream *input,
+                                   GFileInfo *file_info,
+                                   GVariant *xattrs,
+                                   GInputStream **out_input,
+                                   guint64 *out_length,
+                                   GCancellable *cancellable,
+                                   GError **error);
+

Convert from a "bare" file representation into an +OSTREE_OBJECT_TYPE_FILE stream. This is a fundamental operation +for writing data to an OstreeRepo.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

input

File raw content stream

 

file_info

A file info

 

xattrs

Optional extended attributes.

[allow-none]

out_input

Serialized object stream.

[out]

out_length

Length of stream.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_break_hardlink ()

+
gboolean
+ostree_break_hardlink (int dfd,
+                       const char *path,
+                       gboolean skip_xattrs,
+                       GCancellable *cancellable,
+                       GError **error);
+

In many cases using libostree, a program may need to "break" +hardlinks by performing a copy. For example, in order to +logically append to a file.

+

This function performs full copying, including e.g. extended +attributes and permissions of both regular files and symbolic links.

+

If the file is not hardlinked, this function does nothing and +returns successfully.

+

This function does not perform synchronization via fsync() or +fdatasync(); the idea is this will commonly be done as part +of an ostree_repo_commit_transaction(), which itself takes +care of synchronization.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

dfd

Directory fd

 

path

Path relative to dfd +

 

skip_xattrs

Do not copy extended attributes

 

error

error

 
+
+

Since: 2017.15

+
+
+
+

ostree_checksum_file_from_input ()

+
gboolean
+ostree_checksum_file_from_input (GFileInfo *file_info,
+                                 GVariant *xattrs,
+                                 GInputStream *in,
+                                 OstreeObjectType objtype,
+                                 guchar **out_csum,
+                                 GCancellable *cancellable,
+                                 GError **error);
+

Compute the OSTree checksum for a given input.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

file_info

File information

 

xattrs

Optional extended attributes.

[allow-none]

in

File content, should be NULL for symbolic links.

[allow-none]

objtype

Object type

 

out_csum

Return location for binary checksum.

[out][array fixed-size=32]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_checksum_file ()

+
gboolean
+ostree_checksum_file (GFile *f,
+                      OstreeObjectType objtype,
+                      guchar **out_csum,
+                      GCancellable *cancellable,
+                      GError **error);
+

Compute the OSTree checksum for a given file.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

f

File path

 

objtype

Object type

 

out_csum

Return location for binary checksum.

[out][array fixed-size=32]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_checksum_file_at ()

+
gboolean
+ostree_checksum_file_at (int dfd,
+                         const char *path,
+                         struct stat *stbuf,
+                         OstreeObjectType objtype,
+                         OstreeChecksumFlags flags,
+                         char **out_checksum,
+                         GCancellable *cancellable,
+                         GError **error);
+

Compute the OSTree checksum for a given file. This is an fd-relative version +of ostree_checksum_file() which also takes flags and fills in a caller +allocated buffer.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

dfd

Directory file descriptor

 

path

Subpath

 

stbuf (allow-none)

Optional stat buffer

 

objtype

Object type

 

flags

Flags

 

out_checksum (out) (transfer full)

Return location for hex checksum

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2017.13

+
+
+
+

ostree_checksum_file_async ()

+
void
+ostree_checksum_file_async (GFile *f,
+                            OstreeObjectType objtype,
+                            int io_priority,
+                            GCancellable *cancellable,
+                            GAsyncReadyCallback callback,
+                            gpointer user_data);
+

Asynchronously compute the OSTree checksum for a given file; +complete with ostree_checksum_file_async_finish().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

f

File path

 

objtype

Object type

 

io_priority

Priority for operation, see G_IO_PRIORITY_DEFAULT

 

cancellable

Cancellable

 

callback

Invoked when operation is complete

 

user_data

Data for callback +

 
+
+
+
+
+

ostree_checksum_file_async_finish ()

+
gboolean
+ostree_checksum_file_async_finish (GFile *f,
+                                   GAsyncResult *result,
+                                   guchar **out_csum,
+                                   GError **error);
+

Finish computing the OSTree checksum for a given file; see +ostree_checksum_file_async().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

f

File path

 

result

Async result

 

out_csum

Return location for binary checksum.

[out][array fixed-size=32]

error

Error

 
+
+
+
+
+

ostree_fs_get_all_xattrs ()

+
GVariant *
+ostree_fs_get_all_xattrs (int fd,
+                          GCancellable *cancellable,
+                          GError **error);
+

Retrieve all extended attributes in a canonical (sorted) order from +the given file descriptor.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

fd

File descriptor

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

A GVariant of type a(ayay).

+

[transfer full]

+
+
+
+
+

ostree_fs_get_all_xattrs_at ()

+
GVariant *
+ostree_fs_get_all_xattrs_at (int dfd,
+                             const char *path,
+                             GCancellable *cancellable,
+                             GError **error);
+

Retrieve all extended attributes in a canonical (sorted) order from +the given path, relative to the provided directory file descriptor. +The target path will not be dereferenced. Currently on Linux, this +API must be used currently to retrieve extended attributes +for symbolic links because while O_PATH exists, it cannot be used +with fgetxattr().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

dfd

Directory file descriptor

 

path

Filesystem path

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

A GVariant of type a(ayay).

+

[transfer full]

+
+
+
+
+

ostree_create_directory_metadata ()

+
GVariant *
+ostree_create_directory_metadata (GFileInfo *dir_info,
+                                  GVariant *xattrs);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

dir_info

a GFileInfo containing directory information

 

xattrs

Optional extended attributes.

[allow-none]
+
+
+

Returns

+

A new GVariant containing OSTREE_OBJECT_TYPE_DIR_META.

+

[transfer full][not nullable]

+
+
+
+
+

ostree_validate_structureof_objtype ()

+
gboolean
+ostree_validate_structureof_objtype (guchar objtype,
+                                     GError **error);
+
+

Parameters

+
+++++ + + + + + +

error

Error

 
+
+
+

Returns

+

TRUE if objtype +represents a valid object type

+
+
+
+
+

ostree_validate_structureof_csum_v ()

+
gboolean
+ostree_validate_structureof_csum_v (GVariant *checksum,
+                                    GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

checksum

a GVariant of type "ay"

 

error

Error

 
+
+
+

Returns

+

TRUE if checksum +is a valid binary SHA256 checksum

+
+
+
+
+

ostree_validate_structureof_checksum_string ()

+
gboolean
+ostree_validate_structureof_checksum_string
+                               (const char *checksum,
+                                GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

checksum

an ASCII string

 

error

Error

 
+
+
+

Returns

+

TRUE if checksum +is a valid ASCII SHA256 checksum

+
+
+
+
+

ostree_validate_structureof_file_mode ()

+
gboolean
+ostree_validate_structureof_file_mode (guint32 mode,
+                                       GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

mode

A Unix filesystem mode

 

error

Error

 
+
+
+

Returns

+

TRUE if mode +represents a valid file type and permissions

+
+
+
+
+

ostree_validate_structureof_commit ()

+
gboolean
+ostree_validate_structureof_commit (GVariant *commit,
+                                    GError **error);
+

Use this to validate the basic structure of commit +, independent of +any other objects it references.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

commit

A commit object, OSTREE_OBJECT_TYPE_COMMIT

 

error

Error

 
+
+
+

Returns

+

TRUE if commit +is structurally valid

+
+
+
+
+

ostree_validate_structureof_dirtree ()

+
gboolean
+ostree_validate_structureof_dirtree (GVariant *dirtree,
+                                     GError **error);
+

Use this to validate the basic structure of dirtree +, independent of +any other objects it references.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

dirtree

A dirtree object, OSTREE_OBJECT_TYPE_DIR_TREE

 

error

Error

 
+
+
+

Returns

+

TRUE if dirtree +is structurally valid

+
+
+
+
+

ostree_validate_structureof_dirmeta ()

+
gboolean
+ostree_validate_structureof_dirmeta (GVariant *dirmeta,
+                                     GError **error);
+

Use this to validate the basic structure of dirmeta +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

dirmeta

A dirmeta object, OSTREE_OBJECT_TYPE_DIR_META

 

error

Error

 
+
+
+

Returns

+

TRUE if dirmeta +is structurally valid

+
+
+
+
+

ostree_commit_get_parent ()

+
gchar *
+ostree_commit_get_parent (GVariant *commit_variant);
+
+

Parameters

+
+++++ + + + + + +

commit_variant

Variant of type OSTREE_OBJECT_TYPE_COMMIT

 
+
+
+

Returns

+

Checksum of the parent commit of commit_variant +, or NULL +if none.

+

[nullable]

+
+
+
+
+

ostree_commit_get_timestamp ()

+
guint64
+ostree_commit_get_timestamp (GVariant *commit_variant);
+
+

Parameters

+
+++++ + + + + + +

commit_variant

Commit object

 
+
+
+

Returns

+

timestamp in seconds since the Unix epoch, UTC

+
+

Since: 2016.3

+
+
+
+

ostree_commit_metadata_for_bootable ()

+
gboolean
+ostree_commit_metadata_for_bootable (GFile *root,
+                                     GVariantDict *dict,
+                                     GCancellable *cancellable,
+                                     GError **error);
+

Update provided dict + with standard metadata for bootable OSTree commits.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

root

Root filesystem to be committed

 

dict

Dictionary to update

 
+
+

Since: 2021.1

+
+
+
+

ostree_commit_get_content_checksum ()

+
gchar *
+ostree_commit_get_content_checksum (GVariant *commit_variant);
+

There are use cases where one wants a checksum just of the content of a +commit. OSTree commits by default capture the current timestamp, and may have +additional metadata, which means that re-committing identical content +often results in a new checksum.

+

By comparing checksums of content, it's possible to easily distinguish +cases where nothing actually changed.

+

The content checksums is simply defined as SHA256(root dirtree_checksum || +root_dirmeta_checksum), i.e. the SHA-256 of the root "dirtree" object's checksum concatenated +with the root "dirmeta" checksum (both in binary form, not hexadecimal).

+
+

Parameters

+
+++++ + + + + + +

commit_variant

A commit object

 
+
+
+

Returns

+

A SHA-256 hex string, or NULL if commit_variant +is not well-formed.

+

[nullable]

+
+

Since: 2018.2

+
+
+
+

ostree_commit_get_object_sizes ()

+
gboolean
+ostree_commit_get_object_sizes (GVariant *commit_variant,
+                                GPtrArray **out_sizes_entries,
+                                GError **error);
+

Reads a commit's "ostree.sizes" metadata and returns an array of +OstreeCommitSizesEntry in out_sizes_entries +. Each element +represents an object in the commit. If the commit does not contain +the "ostree.sizes" metadata, a G_IO_ERROR_NOT_FOUND error will be +returned.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

commit_variant

variant of type OSTREE_OBJECT_TYPE_COMMIT.

[not nullable]

out_sizes_entries

return location for an array of object size entries.

[out][element-type OstreeCommitSizesEntry][transfer container][optional]

error

Error

 
+
+

Since: 2020.1

+
+
+
+

ostree_commit_sizes_entry_new ()

+
OstreeCommitSizesEntry *
+ostree_commit_sizes_entry_new (const gchar *checksum,
+                               OstreeObjectType objtype,
+                               guint64 unpacked,
+                               guint64 archived);
+

Create a new OstreeCommitSizesEntry for representing an object in a +commit's "ostree.sizes" metadata.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

checksum

object checksum.

[not nullable]

objtype

object type

 

unpacked

unpacked object size

 

archived

compressed object size

 
+
+
+

Returns

+

a new OstreeCommitSizesEntry.

+

[transfer full][nullable]

+
+

Since: 2020.1

+
+
+
+

ostree_commit_sizes_entry_copy ()

+
OstreeCommitSizesEntry *
+ostree_commit_sizes_entry_copy (const OstreeCommitSizesEntry *entry);
+

Create a copy of the given entry +.

+
+

Parameters

+
+++++ + + + + + +

entry

an OstreeCommitSizesEntry.

[not nullable]
+
+
+

Returns

+

a new copy of entry +.

+

[transfer full][nullable]

+
+

Since: 2020.1

+
+
+
+

ostree_commit_sizes_entry_free ()

+
void
+ostree_commit_sizes_entry_free (OstreeCommitSizesEntry *entry);
+

Free given entry +.

+
+

Parameters

+
+++++ + + + + + +

entry

an OstreeCommitSizesEntry.

[transfer full]
+
+

Since: 2020.1

+
+
+
+

ostree_check_version ()

+
gboolean
+ostree_check_version (guint required_year,
+                      guint required_release);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

required_year

Major/year required

 

required_release

Release version required

 
+
+
+

Returns

+

TRUE if current libostree has at least the requested version, FALSE otherwise

+
+

Since: 2017.4

+
+
+
+

Types and Values

+
+

OSTREE_MAX_METADATA_SIZE

+
#define OSTREE_MAX_METADATA_SIZE (128 * 1024 * 1024)
+
+

Default limit for maximum permitted size in bytes of metadata objects fetched +over HTTP (including repo/config files, refs, and commit/dirtree/dirmeta +objects). This is an arbitrary number intended to mitigate disk space +exhaustion attacks.

+
+
+
+

OSTREE_MAX_METADATA_WARN_SIZE

+
#define OSTREE_MAX_METADATA_WARN_SIZE (7 * 1024 * 1024)
+
+

This variable is no longer meaningful, it is kept only for compatibility.

+
+
+
+

enum OstreeObjectType

+

Enumeration for core object types; OSTREE_OBJECT_TYPE_FILE is for +content, the other types are metadata.

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_OBJECT_TYPE_FILE

+

Content; regular file, symbolic link

+
 

OSTREE_OBJECT_TYPE_DIR_TREE

+

List of children (trees or files), and metadata

+
 

OSTREE_OBJECT_TYPE_DIR_META

+

Directory metadata

+
 

OSTREE_OBJECT_TYPE_COMMIT

+

Toplevel object, refers to tree and dirmeta for root

+
 

OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT

+

Toplevel object, refers to a deleted commit

+
 

OSTREE_OBJECT_TYPE_COMMIT_META

+

Detached metadata for a commit

+
 

OSTREE_OBJECT_TYPE_PAYLOAD_LINK

+

Symlink to a .file given its checksum on the payload only.

+
 

OSTREE_OBJECT_TYPE_FILE_XATTRS

+

Detached xattrs content, for 'bare-split-xattrs' mode.

+
 

OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK

+

Hardlink to a .file-xattrs given the checksum of its .file +object.

+
 
+
+
+
+
+

OSTREE_OBJECT_TYPE_LAST

+
#define OSTREE_OBJECT_TYPE_LAST OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK
+
+

Last valid object type; use this to validate ranges.

+
+
+
+

OSTREE_DIRMETA_GVARIANT_STRING

+
#define OSTREE_DIRMETA_GVARIANT_STRING "(uuua(ayay))"
+
+
+
+
+

OSTREE_DIRMETA_GVARIANT_FORMAT

+
#define OSTREE_DIRMETA_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_DIRMETA_GVARIANT_STRING)
+
+
    +
  • u - uid (big-endian)

  • +
  • u - gid (big-endian)

  • +
  • u - mode (big-endian)

  • +
  • a(ayay) - xattrs

  • +
+
+
+
+

OSTREE_FILEMETA_GVARIANT_STRING

+
#define OSTREE_FILEMETA_GVARIANT_STRING "(uuua(ayay))"
+
+
+
+
+

OSTREE_FILEMETA_GVARIANT_FORMAT

+
#define OSTREE_FILEMETA_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_FILEMETA_GVARIANT_STRING)
+
+

This is not a regular object type, but used as an xattr on a .file object +in bare-user repositories. This allows us to store metadata information that we +can't store in the real filesystem but we can still use a regular .file object +that we can hardlink to in the case of a user-mode checkout.

+
    +
  • u - uid (big-endian)

  • +
  • u - gid (big-endian)

  • +
  • u - mode (big-endian)

  • +
  • a(ayay) - xattrs

  • +
+
+
+
+

OSTREE_TREE_GVARIANT_STRING

+
#define OSTREE_TREE_GVARIANT_STRING "(a(say)a(sayay))"
+
+
+
+
+

OSTREE_TREE_GVARIANT_FORMAT

+
#define OSTREE_TREE_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_TREE_GVARIANT_STRING)
+
+
    +
  • a(say) - array of (filename, checksum) for files

  • +
  • a(sayay) - array of (dirname, tree_checksum, meta_checksum) for directories

  • +
+
+
+
+

OSTREE_COMMIT_GVARIANT_STRING

+
#define OSTREE_COMMIT_GVARIANT_STRING "(a{sv}aya(say)sstayay)"
+
+
+
+
+

OSTREE_COMMIT_GVARIANT_FORMAT

+
#define OSTREE_COMMIT_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_COMMIT_GVARIANT_STRING)
+
+
    +
  • a{sv} - Metadata

  • +
  • ay - parent checksum (empty string for initial)

  • +
  • a(say) - Related objects

  • +
  • s - subject

  • +
  • s - body

  • +
  • t - Timestamp in seconds since the epoch (UTC, big-endian)

  • +
  • ay - Root tree contents

  • +
  • ay - Root tree metadata

  • +
+
+
+
+

OSTREE_SUMMARY_GVARIANT_STRING

+
#define OSTREE_SUMMARY_GVARIANT_STRING "(a(s(taya{sv}))a{sv})"
+
+
+
+
+

OSTREE_SUMMARY_GVARIANT_FORMAT

+
#define OSTREE_SUMMARY_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_SUMMARY_GVARIANT_STRING)
+
+
    +
  • a(s(taya{sv})) - Map of ref name -> (latest commit size, latest commit checksum, additional +metadata), sorted by ref name

  • +
  • +

    a{sv} - Additional metadata, at the current time the following are defined:

    +
      +
    • key: "ostree.static-deltas", value: a{sv}, static delta name -> 32 bytes of checksum

    • +
    • key: "ostree.summary.last-modified", value: t, timestamp (seconds since +the Unix epoch in UTC, big-endian) when the summary was last regenerated +(similar to the HTTP Last-Modified header)

    • +
    • key: "ostree.summary.expires", value: t, timestamp (seconds since the +Unix epoch in UTC, big-endian) after which the summary is considered +stale and should be re-downloaded if possible (similar to the HTTP +Expires header)

    • +
    +
  • +
+

The currently defined keys for the a{sv} of additional metadata for each commit are:

+
    +
  • key: ostree.commit.timestamp, value: t, timestamp (seconds since the +Unix epoch in UTC, big-endian) when the commit was committed

  • +
  • key: ostree.commit.version, value: s, the version value from the +commit's metadata if it was defined. Since: 2022.2

  • +
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-GPG-signature-verification-results.html b/reference/ostree-GPG-signature-verification-results.html new file mode 100644 index 0000000000..fae0c5522c --- /dev/null +++ b/reference/ostree-GPG-signature-verification-results.html @@ -0,0 +1,757 @@ + + + + +GPG signature verification results: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

GPG signature verification results

+

GPG signature verification results — Inspect detached GPG signatures

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+guint + +ostree_gpg_verify_result_count_all () +
+guint + +ostree_gpg_verify_result_count_valid () +
+gboolean + +ostree_gpg_verify_result_lookup () +
+GVariant * + +ostree_gpg_verify_result_get () +
+GVariant * + +ostree_gpg_verify_result_get_all () +
+void + +ostree_gpg_verify_result_describe () +
+void + +ostree_gpg_verify_result_describe_variant () +
+gboolean + +ostree_gpg_verify_result_require_valid_signature () +
+
+
+

Types and Values

+
++++ + + + + + + + + + + + + + + + + + + +
enumOstreeGpgError
typedefOstreeGpgVerifyResult
enumOstreeGpgSignatureAttr
enumOstreeGpgSignatureFormatFlags
+
+
+

Description

+

OstreeGpgVerifyResult contains verification details for GPG signatures +read from a detached OstreeRepo metadata object.

+

Use ostree_gpg_verify_result_count_all() and +ostree_gpg_verify_result_count_valid() to quickly check overall signature +validity.

+

Use ostree_gpg_verify_result_lookup() to find a signature by the key ID +or fingerprint of the signing key.

+

For more in-depth inspection, such as presenting signature details to the +user, pass an array of attribute values to ostree_gpg_verify_result_get() +or get all signature details with ostree_gpg_verify_result_get_all().

+
+
+

Functions

+
+

ostree_gpg_verify_result_count_all ()

+
guint
+ostree_gpg_verify_result_count_all (OstreeGpgVerifyResult *result);
+

Counts all the signatures in result +.

+
+

Parameters

+
+++++ + + + + + +

result

an OstreeGpgVerifyResult

 
+
+
+

Returns

+

signature count

+
+
+
+
+

ostree_gpg_verify_result_count_valid ()

+
guint
+ostree_gpg_verify_result_count_valid (OstreeGpgVerifyResult *result);
+

Counts only the valid signatures in result +.

+
+

Parameters

+
+++++ + + + + + +

result

an OstreeGpgVerifyResult

 
+
+
+

Returns

+

valid signature count

+
+
+
+
+

ostree_gpg_verify_result_lookup ()

+
gboolean
+ostree_gpg_verify_result_lookup (OstreeGpgVerifyResult *result,
+                                 const gchar *key_id,
+                                 guint *out_signature_index);
+

Searches result + for a signature signed by key_id +. If a match is found, +the function returns TRUE and sets out_signature_index + so that further +signature details can be obtained through ostree_gpg_verify_result_get(). +If no match is found, the function returns FALSE and leaves +out_signature_index + unchanged.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

result

an OstreeGpgVerifyResult

 

key_id

a GPG key ID or fingerprint

 

out_signature_index

return location for the index of the signature +signed by key_id +, or NULL.

[out]
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+
+
+
+

ostree_gpg_verify_result_get ()

+
GVariant *
+ostree_gpg_verify_result_get (OstreeGpgVerifyResult *result,
+                              guint signature_index,
+                              OstreeGpgSignatureAttr *attrs,
+                              guint n_attrs);
+

Builds a GVariant tuple of requested attributes for the GPG signature at +signature_index + in result +. See the OstreeGpgSignatureAttr description +for the GVariantType of each available attribute.

+

It is a programmer error to request an invalid OstreeGpgSignatureAttr or +an invalid signature_index +. Use ostree_gpg_verify_result_count_all() to +find the number of signatures in result +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

result

an OstreeGpgVerifyResult

 

signature_index

which signature to get attributes from

 

attrs

Array of requested attributes.

[array length=n_attrs]

n_attrs

Length of the attrs +array

 
+
+
+

Returns

+

a new, floating, GVariant tuple.

+

[transfer floating]

+
+
+
+
+

ostree_gpg_verify_result_get_all ()

+
GVariant *
+ostree_gpg_verify_result_get_all (OstreeGpgVerifyResult *result,
+                                  guint signature_index);
+

Builds a GVariant tuple of all available attributes for the GPG signature +at signature_index + in result +.

+

The child values in the returned GVariant tuple are ordered to match the +OstreeGpgSignatureAttr enumeration, which means the enum values can be +used as index values in functions like g_variant_get_child(). See the +OstreeGpgSignatureAttr description for the GVariantType of each +available attribute.

+

+ The OstreeGpgSignatureAttr enumeration may be extended in the future + with new attributes, which would affect the GVariant tuple returned by + this function. While the position and type of current child values in + the GVariant tuple will not change, to avoid backward-compatibility + issues please do not depend on the tuple's overall size or + type signature. +

+

It is a programmer error to request an invalid signature_index +. Use +ostree_gpg_verify_result_count_all() to find the number of signatures in +result +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

result

an OstreeGpgVerifyResult

 

signature_index

which signature to get attributes from

 
+
+
+

Returns

+

a new, floating, GVariant tuple.

+

[transfer floating]

+
+
+
+
+

ostree_gpg_verify_result_describe ()

+
void
+ostree_gpg_verify_result_describe (OstreeGpgVerifyResult *result,
+                                   guint signature_index,
+                                   GString *output_buffer,
+                                   const gchar *line_prefix,
+                                   OstreeGpgSignatureFormatFlags flags);
+

Appends a brief, human-readable description of the GPG signature at +signature_index + in result + to the output_buffer +. The description +spans multiple lines. A line_prefix + string, if given, will precede +each line of the description.

+

The flags + argument is reserved for future variations to the description +format. Currently must be 0.

+

It is a programmer error to request an invalid signature_index +. Use +ostree_gpg_verify_result_count_all() to find the number of signatures in +result +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

result

an OstreeGpgVerifyResult

 

signature_index

which signature to describe

 

output_buffer

a GString to hold the description

 

line_prefix

optional line prefix string.

[allow-none]

flags

flags to adjust the description format

 
+
+
+
+
+

ostree_gpg_verify_result_describe_variant ()

+
void
+ostree_gpg_verify_result_describe_variant
+                               (GVariant *variant,
+                                GString *output_buffer,
+                                const gchar *line_prefix,
+                                OstreeGpgSignatureFormatFlags flags);
+

Similar to ostree_gpg_verify_result_describe() but takes a GVariant of +all attributes for a GPG signature instead of an OstreeGpgVerifyResult +and signature index.

+

The variant + MUST have been created by +ostree_gpg_verify_result_get_all().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

variant

a GVariant from ostree_gpg_verify_result_get_all()

 

output_buffer

a GString to hold the description

 

line_prefix

optional line prefix string.

[allow-none]

flags

flags to adjust the description format

 
+
+
+
+
+

ostree_gpg_verify_result_require_valid_signature ()

+
gboolean
+ostree_gpg_verify_result_require_valid_signature
+                               (OstreeGpgVerifyResult *result,
+                                GError **error);
+

Checks if the result contains at least one signature from the +trusted keyring. You can call this function immediately after +ostree_repo_verify_summary() or ostree_repo_verify_commit_ext() - +it will handle the NULL result + and filled error + too.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

result

an OstreeGpgVerifyResult.

[nullable]

error

A GError

 
+
+
+

Returns

+

TRUE if result +was not NULL and had at least one +signature from trusted keyring, otherwise FALSE

+
+

Since: 2016.6

+
+
+
+

Types and Values

+
+

enum OstreeGpgError

+

Errors returned by signature creation and verification operations in OSTree. +These may be returned by any API which creates or verifies signatures.

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_GPG_ERROR_NO_SIGNATURE

+

A signature was expected, but not found.

+
 

OSTREE_GPG_ERROR_INVALID_SIGNATURE

+

A signature was malformed.

+
 

OSTREE_GPG_ERROR_MISSING_KEY

+

A signature was found, but was created with a key not in the +configured keyrings.

+
 

OSTREE_GPG_ERROR_EXPIRED_SIGNATURE

+

A signature was expired. Since: 2020.1.

+
 

OSTREE_GPG_ERROR_EXPIRED_KEY

+

A signature was found, but the key used to +sign it has expired. Since: 2020.1.

+
 

OSTREE_GPG_ERROR_REVOKED_KEY

+

A signature was found, but the key used to +sign it has been revoked. Since: 2020.1.

+
 
+
+

Since: 2017.10

+
+
+
+

OstreeGpgVerifyResult

+
typedef struct OstreeGpgVerifyResult OstreeGpgVerifyResult;
+
+

Private instance structure.

+
+
+
+

enum OstreeGpgSignatureAttr

+

Signature attributes available from an OstreeGpgVerifyResult. +The attribute's GVariantType is shown in brackets.

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_GPG_SIGNATURE_ATTR_VALID

+

[G_VARIANT_TYPE_BOOLEAN] Is the signature valid?

+
 

OSTREE_GPG_SIGNATURE_ATTR_SIG_EXPIRED

+

[G_VARIANT_TYPE_BOOLEAN] Has the signature expired?

+
 

OSTREE_GPG_SIGNATURE_ATTR_KEY_EXPIRED

+

[G_VARIANT_TYPE_BOOLEAN] Has the signing key expired?

+
 

OSTREE_GPG_SIGNATURE_ATTR_KEY_REVOKED

+

[G_VARIANT_TYPE_BOOLEAN] Has the signing key been revoked?

+
 

OSTREE_GPG_SIGNATURE_ATTR_KEY_MISSING

+

[G_VARIANT_TYPE_BOOLEAN] Is the signing key missing?

+
 

OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT

+

[G_VARIANT_TYPE_STRING] Fingerprint of the signing key

+
 

OSTREE_GPG_SIGNATURE_ATTR_TIMESTAMP

+

[G_VARIANT_TYPE_INT64] Signature creation Unix timestamp

+
 

OSTREE_GPG_SIGNATURE_ATTR_EXP_TIMESTAMP

+

[G_VARIANT_TYPE_INT64] Signature expiration Unix timestamp (0 if no +expiration)

+
 

OSTREE_GPG_SIGNATURE_ATTR_PUBKEY_ALGO_NAME

+

[G_VARIANT_TYPE_STRING] Name of the public key algorithm used to create +the signature

+
 

OSTREE_GPG_SIGNATURE_ATTR_HASH_ALGO_NAME

+

[G_VARIANT_TYPE_STRING] Name of the hash algorithm used to create the +signature

+
 

OSTREE_GPG_SIGNATURE_ATTR_USER_NAME

+

[G_VARIANT_TYPE_STRING] The name of the signing key's primary user

+
 

OSTREE_GPG_SIGNATURE_ATTR_USER_EMAIL

+

[G_VARIANT_TYPE_STRING] The email address of the signing key's primary +user

+
 

OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT_PRIMARY

+

[G_VARIANT_TYPE_STRING] Fingerprint of the signing key's primary key +(will be the same as OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT if the +the signature is already from the primary key rather than a subkey, +and will be the empty string if the key is missing.)

+
 

OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP

+

[G_VARIANT_TYPE_INT64] Key expiration Unix timestamp (0 if no +expiration or if the key is missing)

+
 

OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP_PRIMARY

+

[G_VARIANT_TYPE_INT64] Key expiration Unix timestamp of the signing key's +primary key (will be the same as OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP +if the signing key is the primary key and 0 if no expiration or if the key +is missing)

+
 
+
+
+
+
+

enum OstreeGpgSignatureFormatFlags

+

Formatting flags for ostree_gpg_verify_result_describe(). Currently +there's only one possible output format, but this enumeration allows +for future variations.

+
+

Members

+
+++++ + + + + + +

OSTREE_GPG_SIGNATURE_FORMAT_DEFAULT

+

Use the default output format

+
 
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-In-memory-modifiable-filesystem-tree.html b/reference/ostree-In-memory-modifiable-filesystem-tree.html new file mode 100644 index 0000000000..f06af25585 --- /dev/null +++ b/reference/ostree-In-memory-modifiable-filesystem-tree.html @@ -0,0 +1,685 @@ + + + + +In-memory modifiable filesystem tree: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

In-memory modifiable filesystem tree

+

In-memory modifiable filesystem tree — Modifiable filesystem tree

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+OstreeMutableTree * + +ostree_mutable_tree_new () +
+OstreeMutableTree * + +ostree_mutable_tree_new_from_commit () +
+OstreeMutableTree * + +ostree_mutable_tree_new_from_checksum () +
+gboolean + +ostree_mutable_tree_check_error () +
+void + +ostree_mutable_tree_set_metadata_checksum () +
const char * + +ostree_mutable_tree_get_metadata_checksum () +
+void + +ostree_mutable_tree_set_contents_checksum () +
const char * + +ostree_mutable_tree_get_contents_checksum () +
+gboolean + +ostree_mutable_tree_replace_file () +
+gboolean + +ostree_mutable_tree_remove () +
+gboolean + +ostree_mutable_tree_ensure_dir () +
+gboolean + +ostree_mutable_tree_lookup () +
+gboolean + +ostree_mutable_tree_ensure_parent_dirs () +
+gboolean + +ostree_mutable_tree_walk () +
+GHashTable * + +ostree_mutable_tree_get_subdirs () +
+GHashTable * + +ostree_mutable_tree_get_files () +
+gboolean + +ostree_mutable_tree_fill_empty_from_dirtree () +
+
+
+

Types and Values

+
++++ + + + + +
typedefOstreeMutableTree
+
+
+

Description

+

In order to commit content into an OstreeRepo, it must first be +imported into an OstreeMutableTree. There are several high level +APIs to create an initiable OstreeMutableTree from a physical +filesystem directory, but they may also be computed +programmatically.

+
+
+

Functions

+
+

ostree_mutable_tree_new ()

+
OstreeMutableTree *
+ostree_mutable_tree_new (void);
+
+

Returns

+

A new tree.

+

[transfer full]

+
+
+
+
+

ostree_mutable_tree_new_from_commit ()

+
OstreeMutableTree *
+ostree_mutable_tree_new_from_commit (OstreeRepo *repo,
+                                     const char *rev,
+                                     GError **error);
+

Creates a new OstreeMutableTree with the contents taken from the given commit. +The data will be loaded from the repo lazily as needed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

repo

The repo which contains the objects refered by the checksums.

 

rev

ref or SHA-256 checksum

 
+
+
+

Returns

+

A new tree.

+

[transfer full]

+
+

Since: 2021.5

+
+
+
+

ostree_mutable_tree_new_from_checksum ()

+
OstreeMutableTree *
+ostree_mutable_tree_new_from_checksum (OstreeRepo *repo,
+                                       const char *contents_checksum,
+                                       const char *metadata_checksum);
+

Creates a new OstreeMutableTree with the contents taken from the given repo +and checksums. The data will be loaded from the repo lazily as needed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

repo

The repo which contains the objects refered by the checksums.

 

contents_checksum

dirtree checksum

 

metadata_checksum

dirmeta checksum

 
+
+
+

Returns

+

A new tree.

+

[transfer full]

+
+

Since: 2018.7

+
+
+
+

ostree_mutable_tree_check_error ()

+
gboolean
+ostree_mutable_tree_check_error (OstreeMutableTree *self,
+                                 GError **error);
+

In some cases, a tree may be in a "lazy" state that loads +data in the background; if an error occurred during a non-throwing +API call, it will have been cached. This function checks for a +cached error. The tree remains in error state.

+
+

Parameters

+
+++++ + + + + + +

self

Tree

 
+
+
+

Returns

+

TRUE on success

+
+

Since: 2018.7

+
+
+
+

ostree_mutable_tree_set_metadata_checksum ()

+
void
+ostree_mutable_tree_set_metadata_checksum
+                               (OstreeMutableTree *self,
+                                const char *checksum);
+
+
+
+

ostree_mutable_tree_get_metadata_checksum ()

+
const char *
+ostree_mutable_tree_get_metadata_checksum
+                               (OstreeMutableTree *self);
+
+
+
+

ostree_mutable_tree_set_contents_checksum ()

+
void
+ostree_mutable_tree_set_contents_checksum
+                               (OstreeMutableTree *self,
+                                const char *checksum);
+
+
+
+

ostree_mutable_tree_get_contents_checksum ()

+
const char *
+ostree_mutable_tree_get_contents_checksum
+                               (OstreeMutableTree *self);
+
+
+
+

ostree_mutable_tree_replace_file ()

+
gboolean
+ostree_mutable_tree_replace_file (OstreeMutableTree *self,
+                                  const char *name,
+                                  const char *checksum,
+                                  GError **error);
+
+
+
+

ostree_mutable_tree_remove ()

+
gboolean
+ostree_mutable_tree_remove (OstreeMutableTree *self,
+                            const char *name,
+                            gboolean allow_noent,
+                            GError **error);
+

Remove the file or subdirectory named name + from the mutable tree self +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Tree

 

name

Name of file or subdirectory to remove

 

allow_noent

If FALSE +, an error will be thrown if name +does not exist in the tree

 

error

a GError

 
+
+

Since: 2018.9

+
+
+
+

ostree_mutable_tree_ensure_dir ()

+
gboolean
+ostree_mutable_tree_ensure_dir (OstreeMutableTree *self,
+                                const char *name,
+                                OstreeMutableTree **out_subdir,
+                                GError **error);
+

Returns the subdirectory of self with filename name +, creating an empty one +it if it doesn't exist.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Tree

 

name

Name of subdirectory of self to retrieve/creates

 

out_subdir

the subdirectory.

[out][transfer full][optional]

error

a GError

 
+
+
+
+
+

ostree_mutable_tree_lookup ()

+
gboolean
+ostree_mutable_tree_lookup (OstreeMutableTree *self,
+                            const char *name,
+                            char **out_file_checksum,
+                            OstreeMutableTree **out_subdir,
+                            GError **error);
+

Lookup name + and returns out_file_checksum + or out_subdir + depending on its +file type.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Tree

 

name

name

 

out_file_checksum

checksum.

[out][transfer full][nullable][optional]

out_subdir

subdirectory.

[out][transfer full][nullable][optional]

error

a GError

 
+
+
+

Returns

+

TRUE on success and either out_file_checksum +or out_subdir +are +filled, FALSE otherwise.

+
+
+
+
+

ostree_mutable_tree_ensure_parent_dirs ()

+
gboolean
+ostree_mutable_tree_ensure_parent_dirs
+                               (OstreeMutableTree *self,
+                                GPtrArray *split_path,
+                                const char *metadata_checksum,
+                                OstreeMutableTree **out_parent,
+                                GError **error);
+

Create all parent trees necessary for the given split_path + to +exist.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Tree

 

split_path

File path components.

[element-type utf8]

metadata_checksum

SHA256 checksum for metadata

 

out_parent

The parent tree.

[out][transfer full][optional]

error

a GError

 
+
+
+
+
+

ostree_mutable_tree_walk ()

+
gboolean
+ostree_mutable_tree_walk (OstreeMutableTree *self,
+                          GPtrArray *split_path,
+                          guint start,
+                          OstreeMutableTree **out_subdir,
+                          GError **error);
+

Traverse start + number of elements starting from split_path +; the +child will be returned in out_subdir +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Tree

 

split_path

Split pathname.

[element-type utf8]

start

Descend from this number of elements in split_path +

 

out_subdir

Target parent.

[out][transfer full]

error

Error

 
+
+
+
+
+

ostree_mutable_tree_get_subdirs ()

+
GHashTable *
+ostree_mutable_tree_get_subdirs (OstreeMutableTree *self);
+
+

Returns

+

All children directories.

+

[transfer none][element-type utf8 OstreeMutableTree]

+
+
+
+
+

ostree_mutable_tree_get_files ()

+
GHashTable *
+ostree_mutable_tree_get_files (OstreeMutableTree *self);
+
+

Returns

+

All children files (the value is a checksum).

+

[transfer none][element-type utf8 utf8]

+
+
+
+
+

ostree_mutable_tree_fill_empty_from_dirtree ()

+
gboolean
+ostree_mutable_tree_fill_empty_from_dirtree
+                               (OstreeMutableTree *self,
+                                OstreeRepo *repo,
+                                const char *contents_checksum,
+                                const char *metadata_checksum);
+

Merges self + with the tree given by contents_checksum + and +metadata_checksum +, but only if it's possible without writing new objects to +the repo +. We can do this if either self + is empty, the tree given by +contents_checksum + is empty or if both trees already have the same +contents_checksum +.

+
+

Returns

+

TRUE +if merge was successful, FALSE +if it was not possible.

+

This function enables optimisations when composing trees. The provided +checksums are not loaded or checked when this function is called. Instead +the contents will be loaded only when needed.

+
+

Since: 2018.7

+
+
+
+

Types and Values

+
+

OstreeMutableTree

+
typedef struct OstreeMutableTree OstreeMutableTree;
+
+

Private instance structure.

+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-OstreeRepo.html b/reference/ostree-OstreeRepo.html new file mode 100644 index 0000000000..4410a3982c --- /dev/null +++ b/reference/ostree-OstreeRepo.html @@ -0,0 +1,10655 @@ + + + + +OstreeRepo: Content-addressed object store: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

OstreeRepo: Content-addressed object store

+

OstreeRepo: Content-addressed object store — A git-like storage system for operating system binaries

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+gboolean + +ostree_repo_mode_from_string () +
+OstreeRepo * + +ostree_repo_open_at () +
+OstreeRepo * + +ostree_repo_new () +
+OstreeRepo * + +ostree_repo_new_for_sysroot_path () +
+OstreeRepo * + +ostree_repo_new_default () +
+gboolean + +ostree_repo_open () +
+void + +ostree_repo_set_disable_fsync () +
+gboolean + +ostree_repo_get_disable_fsync () +
+gboolean + +ostree_repo_is_system () +
+gboolean + +ostree_repo_is_writable () +
+OstreeRepo * + +ostree_repo_create_at () +
+gboolean + +ostree_repo_create () +
const gchar * + +ostree_repo_get_collection_id () +
const gchar * + +ostree_repo_get_bootloader () +
+GFile * + +ostree_repo_get_path () +
+OstreeRepoMode + +ostree_repo_get_mode () +
+gboolean + +ostree_repo_get_min_free_space_bytes () +
+GKeyFile * + +ostree_repo_get_config () +
+int + +ostree_repo_get_dfd () +
const gchar *const * + +ostree_repo_get_default_repo_finders () +
+gboolean + +ostree_repo_lock_pop () +
+gboolean + +ostree_repo_lock_push () +
+OstreeRepoAutoLock * + +ostree_repo_auto_lock_push () +
+void + +ostree_repo_auto_lock_cleanup () +
+guint + +ostree_repo_hash () +
+gboolean + +ostree_repo_equal () +
+GKeyFile * + +ostree_repo_copy_config () +
+gboolean + +ostree_repo_remote_add () +
+gboolean + +ostree_repo_remote_delete () +
+gboolean + +ostree_repo_remote_change () +
+char ** + +ostree_repo_remote_list () +
+gboolean + +ostree_repo_remote_list_collection_refs () +
+gboolean + +ostree_repo_remote_get_url () +
+gboolean + +ostree_repo_remote_get_gpg_verify () +
+gboolean + +ostree_repo_remote_get_gpg_verify_summary () +
+gboolean + +ostree_repo_remote_get_gpg_keys () +
+gboolean + +ostree_repo_remote_gpg_import () +
+gboolean + +ostree_repo_remote_fetch_summary () +
+gboolean + +ostree_repo_remote_fetch_summary_with_options () +
+gboolean + +ostree_repo_reload_config () +
+gboolean + +ostree_repo_get_remote_boolean_option () +
+gboolean + +ostree_repo_get_remote_list_option () +
+gboolean + +ostree_repo_get_remote_option () +
+OstreeRepo * + +ostree_repo_get_parent () +
+gboolean + +ostree_repo_write_config () +
+gboolean + +ostree_repo_scan_hardlinks () +
+gboolean + +ostree_repo_prepare_transaction () +
+gboolean + +ostree_repo_commit_transaction () +
+gboolean + +ostree_repo_abort_transaction () +
+void + +ostree_repo_transaction_set_refspec () +
+void + +ostree_repo_transaction_set_collection_ref () +
+void + +ostree_repo_transaction_set_ref () +
+gboolean + +ostree_repo_set_ref_immediate () +
+gboolean + +ostree_repo_set_alias_ref_immediate () +
+gboolean + +ostree_repo_set_cache_dir () +
+gboolean + +ostree_repo_set_collection_id () +
+gboolean + +ostree_repo_set_collection_ref_immediate () +
+gboolean + +ostree_repo_sign_delta () +
+gboolean + +ostree_repo_has_object () +
+gboolean + +ostree_repo_mark_commit_partial () +
+gboolean + +ostree_repo_mark_commit_partial_reason () +
+gboolean + +ostree_repo_write_metadata () +
+void + +ostree_repo_write_metadata_async () +
+gboolean + +ostree_repo_write_metadata_finish () +
+gboolean + +ostree_repo_write_content () +
+OstreeContentWriter * + +ostree_repo_write_regfile () +
+char * + +ostree_repo_write_regfile_inline () +
+char * + +ostree_repo_write_symlink () +
+gboolean + +ostree_repo_write_metadata_trusted () +
+gboolean + +ostree_repo_write_metadata_stream_trusted () +
+gboolean + +ostree_repo_write_content_trusted () +
+void + +ostree_repo_write_content_async () +
+gboolean + +ostree_repo_write_content_finish () +
+gboolean + +ostree_repo_resolve_rev () +
+gboolean + +ostree_repo_resolve_rev_ext () +
+gboolean + +ostree_repo_list_refs () +
+gboolean + +ostree_repo_list_refs_ext () +
+gboolean + +ostree_repo_list_collection_refs () +
+gboolean + +ostree_repo_remote_list_refs () +
+gboolean + +ostree_repo_resolve_collection_ref () +
+gboolean + +ostree_repo_load_variant () +
+gboolean + +ostree_repo_load_commit () +
+gboolean + +ostree_repo_load_variant_if_exists () +
+gboolean + +ostree_repo_load_file () +
+gboolean + +ostree_repo_load_object_stream () +
+gboolean + +ostree_repo_query_object_storage_size () +
+gboolean + +ostree_repo_import_object_from () +
+gboolean + +ostree_repo_import_object_from_with_trust () +
+gboolean + +ostree_repo_import_archive_to_mtree () +
+gboolean + +ostree_repo_export_tree_to_archive () +
+gboolean + +ostree_repo_delete_object () +
+gboolean + +ostree_repo_fsck_object () +
+OstreeRepoCommitFilterResult + +(*OstreeRepoCommitFilter) () +
+OstreeRepoCommitModifier * + +ostree_repo_commit_modifier_new () +
+GVariant * + +(*OstreeRepoCommitModifierXattrCallback) () +
+void + +ostree_repo_commit_modifier_set_xattr_callback () +
+void + +ostree_repo_commit_modifier_set_sepolicy () +
+gboolean + +ostree_repo_commit_modifier_set_sepolicy_from_commit () +
+void + +ostree_repo_commit_modifier_set_devino_cache () +
+OstreeRepoCommitModifier * + +ostree_repo_commit_modifier_ref () +
+void + +ostree_repo_commit_modifier_unref () +
+OstreeRepoDevInoCache * + +ostree_repo_devino_cache_new () +
+OstreeRepoDevInoCache * + +ostree_repo_devino_cache_ref () +
+void + +ostree_repo_devino_cache_unref () +
+GType + +ostree_repo_devino_cache_get_type () +
+gboolean + +ostree_repo_write_directory_to_mtree () +
+gboolean + +ostree_repo_write_dfd_to_mtree () +
+gboolean + +ostree_repo_write_archive_to_mtree () +
+gboolean + +ostree_repo_write_archive_to_mtree_from_fd () +
+gboolean + +ostree_repo_write_mtree () +
+gboolean + +ostree_repo_write_commit () +
+gboolean + +ostree_repo_write_commit_with_time () +
+gboolean + +ostree_repo_read_commit_detached_metadata () +
+gboolean + +ostree_repo_write_commit_detached_metadata () +
+gboolean + +ostree_repo_commit_add_composefs_metadata () +
+void + +ostree_repo_checkout_at_options_set_devino () +
+gboolean + +ostree_repo_checkout_tree () +
+gboolean + +ostree_repo_checkout_tree_at () +
+gboolean + +ostree_repo_checkout_at () +
+gboolean + +ostree_repo_checkout_gc () +
+gboolean + +ostree_repo_read_commit () +
+gboolean + +ostree_repo_list_objects () +
+gboolean + +ostree_repo_list_commit_objects_starting_with () +
+gboolean + +ostree_repo_list_static_delta_names () +
+gboolean + +ostree_repo_list_static_delta_indexes () +
+gboolean + +ostree_repo_static_delta_reindex () +
+gboolean + +ostree_repo_static_delta_generate () +
+gboolean + +ostree_repo_static_delta_execute_offline_with_signature () +
+gboolean + +ostree_repo_static_delta_execute_offline () +
+gboolean + +ostree_repo_static_delta_verify_signature () +
+GHashTable * + +ostree_repo_traverse_new_reachable () +
+GHashTable * + +ostree_repo_traverse_new_parents () +
+char ** + +ostree_repo_traverse_parents_get_commits () +
+gboolean + +ostree_repo_traverse_commit () +
+gboolean + +ostree_repo_traverse_commit_union () +
+gboolean + +ostree_repo_traverse_commit_union_with_parents () +
+gboolean + +ostree_repo_traverse_commit_with_flags () +
+void + +ostree_repo_commit_traverse_iter_cleanup () +
+void + +ostree_repo_commit_traverse_iter_clear () +
+void + +ostree_repo_commit_traverse_iter_get_dir () +
+void + +ostree_repo_commit_traverse_iter_get_file () +
+gboolean + +ostree_repo_commit_traverse_iter_init_commit () +
+gboolean + +ostree_repo_commit_traverse_iter_init_dirtree () +
+OstreeRepoCommitIterResult + +ostree_repo_commit_traverse_iter_next () +
+gboolean + +ostree_repo_prune () +
+gboolean + +ostree_repo_prune_static_deltas () +
+gboolean + +ostree_repo_traverse_reachable_refs () +
+gboolean + +ostree_repo_prune_from_reachable () +
+gboolean + +ostree_repo_pull () +
+gboolean + +ostree_repo_pull_one_dir () +
+gboolean + +ostree_repo_pull_with_options () +
+void + +ostree_repo_pull_default_console_progress_changed () +
+gboolean + +ostree_repo_sign_commit () +
+gboolean + +ostree_repo_append_gpg_signature () +
+gboolean + +ostree_repo_add_gpg_signature_summary () +
+gboolean + +ostree_repo_gpg_sign_data () +
+OstreeGpgVerifyResult * + +ostree_repo_gpg_verify_data () +
+gboolean + +ostree_repo_signature_verify_commit_data () +
+gboolean + +ostree_repo_verify_commit () +
+OstreeGpgVerifyResult * + +ostree_repo_verify_commit_ext () +
+OstreeGpgVerifyResult * + +ostree_repo_verify_commit_for_remote () +
+OstreeGpgVerifyResult * + +ostree_repo_verify_summary () +
+gboolean + +ostree_repo_regenerate_metadata () +
+gboolean + +ostree_repo_regenerate_summary () +
+
+ +
+

Description

+

The OstreeRepo is like git, a content-addressed object store. +Unlike git, it records uid, gid, and extended attributes.

+

There are four possible "modes" for an OstreeRepo; OSTREE_REPO_MODE_BARE +is very simple - content files are represented exactly as they are, and +checkouts are just hardlinks. OSTREE_REPO_MODE_BARE_USER is similar, except +the uid/gids are not set on the files, and checkouts as hardlinks work only +for user checkouts. OSTREE_REPO_MODE_BARE_USER_ONLY is the same as +BARE_USER, but all metadata is not stored, so it can only be used for user +checkouts. This mode does not require xattrs. A OSTREE_REPO_MODE_ARCHIVE +(also known as OSTREE_REPO_MODE_ARCHIVE_Z2) repository in contrast stores +content files zlib-compressed. It is suitable for non-root-owned +repositories that can be served via a static HTTP server.

+

Creating an OstreeRepo does not invoke any file I/O, and thus needs +to be initialized, either from existing contents or as a new +repository. If you have an existing repo, use ostree_repo_open() +to load it from disk and check its validity. To initialize a new +repository in the given filepath, use ostree_repo_create() instead.

+

To store content in the repo, first start a transaction with +ostree_repo_prepare_transaction(). Then create a +OstreeMutableTree, and apply functions such as +ostree_repo_write_directory_to_mtree() to traverse a physical +filesystem and write content, possibly multiple times.

+

Once the OstreeMutableTree is complete, write all of its metadata +with ostree_repo_write_mtree(), and finally create a commit with +ostree_repo_write_commit().

+
+

Collection IDs

+

A collection ID is a globally unique identifier which, if set, is used to +identify refs from a repository which are mirrored elsewhere, such as in +mirror repositories or peer to peer networks.

+

This is separate from the collection-id configuration key for a remote, which +is used to store the collection ID of the repository that remote points to.

+

The collection ID should only be set on an OstreeRepo if it is the canonical +collection for some refs.

+

A collection ID must be a reverse DNS name, where the domain name is under the +control of the curator of the collection, so they can demonstrate ownership +of the collection. The later elements in the reverse DNS name can be used to +disambiguate between multiple collections from the same curator. For example, +org.exampleos.Main and org.exampleos.Apps. For the complete format of +collection IDs, see ostree_validate_collection_id().

+
+
+
+

Functions

+
+

ostree_repo_mode_from_string ()

+
gboolean
+ostree_repo_mode_from_string (const char *mode,
+                              OstreeRepoMode *out_mode,
+                              GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

mode

a repo mode as a string

 

out_mode

the corresponding OstreeRepoMode.

[out]

error

a GError if the string is not a valid mode

 
+
+
+
+
+

ostree_repo_open_at ()

+
OstreeRepo *
+ostree_repo_open_at (int dfd,
+                     const char *path,
+                     GCancellable *cancellable,
+                     GError **error);
+

This combines ostree_repo_new() (but using fd-relative access) with +ostree_repo_open(). Use this when you know you should be operating on an +already extant repository. If you want to create one, use ostree_repo_create_at().

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

dfd

Directory fd

 

path

Path

 
+
+
+

Returns

+

An accessor object for an OSTree repository located at dfd ++ path +.

+

[transfer full]

+
+

Since: 2017.10

+
+
+
+

ostree_repo_new ()

+
OstreeRepo *
+ostree_repo_new (GFile *path);
+
+

Parameters

+
+++++ + + + + + +

path

Path to a repository

 
+
+
+

Returns

+

An accessor object for an OSTree repository located at path +.

+

[transfer full]

+
+
+
+
+

ostree_repo_new_for_sysroot_path ()

+
OstreeRepo *
+ostree_repo_new_for_sysroot_path (GFile *repo_path,
+                                  GFile *sysroot_path);
+

Creates a new OstreeRepo instance, taking the system root path explicitly +instead of assuming "/".

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

repo_path

Path to a repository

 

sysroot_path

Path to the system root

 
+
+
+

Returns

+

An accessor object for the OSTree repository located at repo_path +.

+

[transfer full]

+
+
+
+
+

ostree_repo_new_default ()

+
OstreeRepo *
+ostree_repo_new_default (void);
+

If the current working directory appears to be an OSTree +repository, create a new OstreeRepo object for accessing it. +Otherwise use the path in the OSTREE_REPO environment variable +(if defined) or else the default system repository located at +/ostree/repo.

+
+

Returns

+

An accessor object for an OSTree repository located at /ostree/repo.

+

[transfer full]

+
+
+
+
+

ostree_repo_open ()

+
gboolean
+ostree_repo_open (OstreeRepo *self,
+                  GCancellable *cancellable,
+                  GError **error);
+
+
+
+

ostree_repo_set_disable_fsync ()

+
void
+ostree_repo_set_disable_fsync (OstreeRepo *self,
+                               gboolean disable_fsync);
+

Disable requests to fsync() to stable storage during commits. This +option should only be used by build system tools which are creating +disposable virtual machines, or have higher level mechanisms for +ensuring data consistency.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

An OstreeRepo

 

disable_fsync

If TRUE, do not fsync

 
+
+
+
+
+

ostree_repo_get_disable_fsync ()

+
gboolean
+ostree_repo_get_disable_fsync (OstreeRepo *self);
+

For more information see ostree_repo_set_disable_fsync().

+
+

Parameters

+
+++++ + + + + + +

self

An OstreeRepo

 
+
+
+

Returns

+

Whether or not fsync() is enabled for this repo.

+
+
+
+
+

ostree_repo_is_system ()

+
gboolean
+ostree_repo_is_system (OstreeRepo *repo);
+
+

Parameters

+
+++++ + + + + + +

repo

Repository

 
+
+
+

Returns

+

TRUE if this repository is the root-owned system global repository

+
+
+
+
+

ostree_repo_is_writable ()

+
gboolean
+ostree_repo_is_writable (OstreeRepo *self,
+                         GError **error);
+

Returns whether the repository is writable by the current user. +If the repository is not writable, the error + indicates why.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Repo

 

error

a GError

 
+
+
+

Returns

+

TRUE if this repository is writable

+
+
+
+
+

ostree_repo_create_at ()

+
OstreeRepo *
+ostree_repo_create_at (int dfd,
+                       const char *path,
+                       OstreeRepoMode mode,
+                       GVariant *options,
+                       GCancellable *cancellable,
+                       GError **error);
+

This is a file-descriptor relative version of ostree_repo_create(). +Create the underlying structure on disk for the repository, and call +ostree_repo_open_at() on the result, preparing it for use.

+

If a repository already exists at dfd + + path + (defined by an objects/ +subdirectory existing), then this function will simply call +ostree_repo_open_at(). In other words, this function cannot be used to change +the mode or configuration (repo/config) of an existing repo.

+

The options + dict may contain:

+
  • collection-id: s: Set as collection ID in repo/config (Since 2017.9)

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

dfd

Directory fd

 

path

Path

 

mode

The mode to store the repository in

 

options

a{sv}: See below for accepted keys.

[nullable]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

A new OSTree repository reference.

+

[transfer full]

+
+

Since: 2017.10

+
+
+
+

ostree_repo_create ()

+
gboolean
+ostree_repo_create (OstreeRepo *self,
+                    OstreeRepoMode mode,
+                    GCancellable *cancellable,
+                    GError **error);
+

Create the underlying structure on disk for the repository, and call +ostree_repo_open() on the result, preparing it for use.

+

Since version 2016.8, this function will succeed on an existing +repository, and finish creating any necessary files in a partially +created repository. However, this function cannot change the mode +of an existing repository, and will silently ignore an attempt to +do so.

+

Since 2017.9, "existing repository" is defined by the existence of an +objects subdirectory.

+

This function predates ostree_repo_create_at(). It is an error to call +this function on a repository initialized via ostree_repo_open_at().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

mode

The mode to store the repository in

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_get_collection_id ()

+
const gchar *
+ostree_repo_get_collection_id (OstreeRepo *self);
+

Get the collection ID of this repository. See collection IDs.

+
+

Parameters

+
+++++ + + + + + +

self

an OstreeRepo

 
+
+
+

Returns

+

collection ID for the repository.

+

[nullable]

+
+

Since: 2018.6

+
+
+
+

ostree_repo_get_bootloader ()

+
const gchar *
+ostree_repo_get_bootloader (OstreeRepo *self);
+

Get the bootloader configured. See the documentation for the +"sysroot.bootloader" config key.

+
+

Parameters

+
+++++ + + + + + +

self

an OstreeRepo

 
+
+
+

Returns

+

bootloader configuration for the sysroot.

+

[transfer none]

+
+

Since: 2019.2

+
+
+
+

ostree_repo_get_path ()

+
GFile *
+ostree_repo_get_path (OstreeRepo *self);
+

Note that since the introduction of ostree_repo_open_at(), this function may +return a process-specific path in /proc if the repository was created using +that API. In general, you should avoid use of this API.

+
+

Parameters

+
+++++ + + + + + +

self

Repo

 
+
+
+

Returns

+

Path to repo.

+

[transfer none]

+
+
+
+
+

ostree_repo_get_mode ()

+
OstreeRepoMode
+ostree_repo_get_mode (OstreeRepo *self);
+
+
+
+

ostree_repo_get_min_free_space_bytes ()

+
gboolean
+ostree_repo_get_min_free_space_bytes (OstreeRepo *self,
+                                      guint64 *out_reserved_bytes,
+                                      GError **error);
+

Determine the number of bytes of free disk space that are reserved according +to the repo config and return that number in out_reserved_bytes +. See the +documentation for the core.min-free-space-size and +core.min-free-space-percent repo config options.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Repo

 

out_reserved_bytes

Location to store the result.

[out]

error

Return location for a GError

 
+
+
+

Returns

+

TRUE on success, FALSE otherwise.

+
+

Since: 2018.9

+
+
+
+

ostree_repo_get_config ()

+
GKeyFile *
+ostree_repo_get_config (OstreeRepo *self);
+
+

Returns

+

The repository configuration; do not modify.

+

[transfer none]

+
+
+
+
+

ostree_repo_get_dfd ()

+
int
+ostree_repo_get_dfd (OstreeRepo *self);
+

In some cases it's useful for applications to access the repository +directly; for example, writing content into repo/tmp ensures it's +on the same filesystem. Another case is detecting the mtime on the +repository (to see whether a ref was written).

+
+

Parameters

+
+++++ + + + + + +

self

Repo

 
+
+
+

Returns

+

File descriptor for repository root - owned by self +

+
+

Since: 2016.4

+
+
+
+

ostree_repo_get_default_repo_finders ()

+
const gchar *const *
+ostree_repo_get_default_repo_finders (OstreeRepo *self);
+

Get the set of default repo finders configured. See the documentation for +the "core.default-repo-finders" config key.

+
+

Parameters

+
+++++ + + + + + +

self

an OstreeRepo

 
+
+
+

Returns

+

NULL-terminated array of strings.

+

[array zero-terminated=1][element-type utf8]

+
+

Since: 2018.9

+
+
+
+

ostree_repo_lock_pop ()

+
gboolean
+ostree_repo_lock_pop (OstreeRepo *self,
+                      OstreeRepoLockType lock_type,
+                      GCancellable *cancellable,
+                      GError **error);
+

Release a lock of type lock_type + from the lock state. If the lock state +becomes empty, the repository is unlocked. Otherwise, the lock state only +changes when transitioning from an exclusive lock back to a shared lock. The +requested lock_type + must be the same type that was requested in the call to +ostree_repo_lock_push(). It is a programmer error if these do not match and +the program may abort if the lock would reach an invalid state.

+

ostree_repo_lock_pop() waits for the lock depending on the repository's +lock-timeout-secs configuration. When lock-timeout-secs is -1, a blocking lock is +attempted. Otherwise, the lock is removed non-blocking and +ostree_repo_lock_pop() will sleep synchronously up to lock-timeout-secs seconds +attempting to remove the lock. If the lock cannot be removed within the +timeout, a G_IO_ERROR_WOULD_BLOCK error is returned.

+

If self + is not writable by the user, then no unlocking is attempted and +TRUE is returned.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

a OstreeRepo

 

lock_type

the type of lock to release

 

cancellable

a GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE on success, otherwise FALSE with error +set

+
+

Since: 2021.3

+
+
+
+

ostree_repo_lock_push ()

+
gboolean
+ostree_repo_lock_push (OstreeRepo *self,
+                       OstreeRepoLockType lock_type,
+                       GCancellable *cancellable,
+                       GError **error);
+

Takes a lock on the repository and adds it to the lock state. If lock_type + +is OSTREE_REPO_LOCK_SHARED, a shared lock is taken. If lock_type + is +OSTREE_REPO_LOCK_EXCLUSIVE, an exclusive lock is taken. The actual lock +state is only changed when locking a previously unlocked repository or +upgrading the lock from shared to exclusive. If the requested lock type is +unchanged or would represent a downgrade (exclusive to shared), the lock +state is not changed.

+

ostree_repo_lock_push() waits for the lock depending on the repository's +lock-timeout-secs configuration. When lock-timeout-secs is -1, a blocking lock is +attempted. Otherwise, the lock is taken non-blocking and +ostree_repo_lock_push() will sleep synchronously up to lock-timeout-secs seconds +attempting to acquire the lock. If the lock cannot be acquired within the +timeout, a G_IO_ERROR_WOULD_BLOCK error is returned.

+

If self + is not writable by the user, then no locking is attempted and +TRUE is returned.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

a OstreeRepo

 

lock_type

the type of lock to acquire

 

cancellable

a GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE on success, otherwise FALSE with error +set

+
+

Since: 2021.3

+
+
+
+

ostree_repo_auto_lock_push ()

+
OstreeRepoAutoLock *
+ostree_repo_auto_lock_push (OstreeRepo *self,
+                            OstreeRepoLockType lock_type,
+                            GCancellable *cancellable,
+                            GError **error);
+

Like ostree_repo_lock_push(), but for usage with OstreeRepoAutoLock. The +intended usage is to declare the OstreeRepoAutoLock with g_autoptr() so +that ostree_repo_auto_lock_cleanup() is called when it goes out of scope. +This will automatically release the lock if it was acquired successfully.

+
+ + + + + + + +
1
+2
+3
+4
g_autoptr(OstreeRepoAutoLock) lock = NULL;
+lock = ostree_repo_auto_lock_push (repo, lock_type, cancellable, error);
+if (!lock)
+  return FALSE;
+
+ +

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

a OstreeRepo

 

lock_type

the type of lock to acquire

 

cancellable

a GCancellable

 

error

a GError

 
+
+
+

Returns

+

self +on success, otherwise NULL with error +set

+
+

Since: 2021.3

+
+
+
+

ostree_repo_auto_lock_cleanup ()

+
void
+ostree_repo_auto_lock_cleanup (OstreeRepoAutoLock *lock);
+

A cleanup handler for use with ostree_repo_auto_lock_push(). If lock + is +not NULL, ostree_repo_lock_pop() will be called on it. If +ostree_repo_lock_pop() fails, a critical warning will be emitted.

+

[skip]

+
+

Parameters

+
+++++ + + + + + +

lock

a OstreeRepoAutoLock

 
+
+

Since: 2021.3

+
+
+
+

ostree_repo_hash ()

+
guint
+ostree_repo_hash (OstreeRepo *self);
+

Calculate a hash value for the given open repository, suitable for use when +putting it into a hash table. It is an error to call this on an OstreeRepo +which is not yet open, as a persistent hash value cannot be calculated until +the repository is open and the inode of its root directory has been loaded.

+

This function does no I/O.

+
+

Parameters

+
+++++ + + + + + +

self

an OstreeRepo

 
+
+
+

Returns

+

hash value for the OstreeRepo

+
+

Since: 2017.12

+
+
+
+

ostree_repo_equal ()

+
gboolean
+ostree_repo_equal (OstreeRepo *a,
+                   OstreeRepo *b);
+

Check whether two opened repositories are the same on disk: if their root +directories are the same inode. If a + or b + are not open yet (due to +ostree_repo_open() not being called on them yet), FALSE will be returned.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

a

an OstreeRepo

 

b

an OstreeRepo

 
+
+
+

Returns

+

TRUE if a +and b +are the same repository on disk, FALSE otherwise

+
+

Since: 2017.12

+
+
+
+

ostree_repo_copy_config ()

+
GKeyFile *
+ostree_repo_copy_config (OstreeRepo *self);
+
+

Returns

+

A newly-allocated copy of the repository config.

+

[transfer full]

+
+
+
+
+

ostree_repo_remote_add ()

+
gboolean
+ostree_repo_remote_add (OstreeRepo *self,
+                        const char *name,
+                        const char *url,
+                        GVariant *options,
+                        GCancellable *cancellable,
+                        GError **error);
+

Create a new remote named name + pointing to url +. If options + is +provided, then it will be mapped to GKeyFile entries, where the +GVariant dictionary key is an option string, and the value is +mapped as follows:

+
    +
  • s: g_key_file_set_string()

  • +
  • b: g_key_file_set_boolean()

  • +
  • as: g_key_file_set_string_list()

  • +
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

name

Name of remote

 

url

URL for remote (if URL begins with metalink=, it will be used as such).

[allow-none]

options

GVariant of type a{sv}.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_remote_delete ()

+
gboolean
+ostree_repo_remote_delete (OstreeRepo *self,
+                           const char *name,
+                           GCancellable *cancellable,
+                           GError **error);
+

Delete the remote named name +. It is an error if the provided +remote does not exist.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

name

Name of remote

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_remote_change ()

+
gboolean
+ostree_repo_remote_change (OstreeRepo *self,
+                           GFile *sysroot,
+                           OstreeRepoRemoteChange changeop,
+                           const char *name,
+                           const char *url,
+                           GVariant *options,
+                           GCancellable *cancellable,
+                           GError **error);
+

A combined function handling the equivalent of +ostree_repo_remote_add(), ostree_repo_remote_delete(), with more +options.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

sysroot

System root.

[allow-none]

changeop

Operation to perform

 

name

Name of remote

 

url

URL for remote (if URL begins with metalink=, it will be used as such).

[allow-none]

options

GVariant of type a{sv}.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_remote_list ()

+
char **
+ostree_repo_remote_list (OstreeRepo *self,
+                         guint *out_n_remotes);
+

List available remote names in an OstreeRepo. Remote names are sorted +alphabetically. If no remotes are available the function returns NULL.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Repo

 

out_n_remotes

Number of remotes available.

[out][allow-none]
+
+
+

Returns

+

a NULL-terminated +array of remote names.

+

[array length=out_n_remotes][transfer full]

+
+
+
+
+

ostree_repo_remote_list_collection_refs ()

+
gboolean
+ostree_repo_remote_list_collection_refs
+                               (OstreeRepo *self,
+                                const char *remote_name,
+                                GHashTable **out_all_refs,
+                                GCancellable *cancellable,
+                                GError **error);
+

List refs advertised by remote_name +, including refs which are part of +collections. If the repository at remote_name + has a collection ID set, its +refs will be returned with that collection ID; otherwise, they will be returned +with a NULL collection ID in each OstreeCollectionRef key in out_all_refs +. +Any refs for other collections stored in the repository will also be returned. +No filtering is performed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

remote_name

Name of the remote.

 

out_all_refs

Mapping from collection–ref to checksum.

[out][element-type OstreeCollectionRef utf8][transfer container]

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2018.6

+
+
+
+

ostree_repo_remote_get_url ()

+
gboolean
+ostree_repo_remote_get_url (OstreeRepo *self,
+                            const char *name,
+                            char **out_url,
+                            GError **error);
+

Return the URL of the remote named name + through out_url +. It is an +error if the provided remote does not exist.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

name

Name of remote

 

out_url

Remote's URL.

[out][optional]

error

Error

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+
+
+
+

ostree_repo_remote_get_gpg_verify ()

+
gboolean
+ostree_repo_remote_get_gpg_verify (OstreeRepo *self,
+                                   const char *name,
+                                   gboolean *out_gpg_verify,
+                                   GError **error);
+

Return whether GPG verification is enabled for the remote named name + +through out_gpg_verify +. It is an error if the provided remote does +not exist.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

name

Name of remote

 

out_gpg_verify

Remote's GPG option.

[out][optional]

error

Error

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+
+
+
+

ostree_repo_remote_get_gpg_verify_summary ()

+
gboolean
+ostree_repo_remote_get_gpg_verify_summary
+                               (OstreeRepo *self,
+                                const char *name,
+                                gboolean *out_gpg_verify_summary,
+                                GError **error);
+

Return whether GPG verification of the summary is enabled for the remote +named name + through out_gpg_verify_summary +. It is an error if the provided +remote does not exist.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

name

Name of remote

 

out_gpg_verify_summary

Remote's GPG option.

[out][allow-none]

error

Error

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+
+
+
+

ostree_repo_remote_get_gpg_keys ()

+
gboolean
+ostree_repo_remote_get_gpg_keys (OstreeRepo *self,
+                                 const char *name,
+                                 const char *const *key_ids,
+                                 GPtrArray **out_keys,
+                                 GCancellable *cancellable,
+                                 GError **error);
+

Enumerate the trusted GPG keys for the remote name +. If name + is +NULL, the global GPG keys will be returned. The keys will be +returned in the out_keys + GPtrArray. Each element in the array is a +GVariant of format OSTREE_GPG_KEY_GVARIANT_FORMAT. The key_ids + +array can be used to limit which keys are included. If key_ids + is +NULL, then all keys are included.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeRepo

 

name

name of the remote or NULL.

[nullable]

key_ids

a NULL-terminated array of GPG key IDs to include, or NULL.

[array zero-terminated=1][element-type utf8][nullable]

out_keys

return location for a GPtrArray of the remote's trusted GPG keys, or +NULL.

[out][optional][element-type GVariant][transfer container]

cancellable

a GCancellable, or NULL.

[nullable]

error

return location for a GError, or NULL

 
+
+
+

Returns

+

TRUE if the GPG keys could be enumerated, FALSE otherwise

+
+

Since: 2021.4

+
+
+
+

ostree_repo_remote_gpg_import ()

+
gboolean
+ostree_repo_remote_gpg_import (OstreeRepo *self,
+                               const char *name,
+                               GInputStream *source_stream,
+                               const char *const *key_ids,
+                               guint *out_imported,
+                               GCancellable *cancellable,
+                               GError **error);
+

Imports one or more GPG keys from the open source_stream +, or from the +user's personal keyring if source_stream + is NULL. The key_ids + array +can optionally restrict which keys are imported. If key_ids + is NULL, +then all keys are imported.

+

The imported keys will be used to conduct GPG verification when pulling +from the remote named name +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

name

name of a remote

 

source_stream

a GInputStream, or NULL.

[nullable]

key_ids

a NULL-terminated array of +GPG key IDs, or NULL.

[array zero-terminated=1][element-type utf8][nullable]

out_imported

return location for the number of imported +keys, or NULL.

[out][optional]

cancellable

a GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+
+
+
+

ostree_repo_remote_fetch_summary ()

+
gboolean
+ostree_repo_remote_fetch_summary (OstreeRepo *self,
+                                  const char *name,
+                                  GBytes **out_summary,
+                                  GBytes **out_signatures,
+                                  GCancellable *cancellable,
+                                  GError **error);
+

Tries to fetch the summary file and any GPG signatures on the summary file +over HTTP, and returns the binary data in out_summary + and out_signatures + +respectively.

+

If no summary file exists on the remote server, out_summary + is set to +NULL +. Likewise if the summary file is not signed, out_signatures + is +set to NULL +. In either case the function still returns TRUE.

+

This method does not verify the signature of the downloaded summary file. +Use ostree_repo_verify_summary() for that.

+

Parse the summary data into a GVariant using g_variant_new_from_bytes() +with OSTREE_SUMMARY_GVARIANT_FORMAT as the format string.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

name

name of a remote

 

out_summary

return location for raw summary data, or +NULL.

[out][optional]

out_signatures

return location for raw summary +signature data, or NULL.

[out][optional]

cancellable

a GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+
+
+
+

ostree_repo_remote_fetch_summary_with_options ()

+
gboolean
+ostree_repo_remote_fetch_summary_with_options
+                               (OstreeRepo *self,
+                                const char *name,
+                                GVariant *options,
+                                GBytes **out_summary,
+                                GBytes **out_signatures,
+                                GCancellable *cancellable,
+                                GError **error);
+

Like ostree_repo_remote_fetch_summary(), but supports an extensible set of flags. +The following are currently defined:

+
    +
  • override-url (s): Fetch summary from this URL if remote specifies no metalink in options

  • +
  • http-headers (a(ss)): Additional headers to add to all HTTP requests

  • +
  • append-user-agent (s): Additional string to append to the user agent

  • +
  • n-network-retries (u): Number of times to retry each download on receiving +a transient network error, such as a socket timeout; default is 5, 0 +means return errors without retrying

  • +
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

name

name of a remote

 

options

A GVariant a{sv} with an extensible set of flags.

[nullable]

out_summary

return location for raw summary data, or NULL.

[out][optional]

out_signatures

return location for raw summary signature +data, or NULL.

[out][optional]

cancellable

a GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+

Since: 2016.6

+
+
+
+

ostree_repo_reload_config ()

+
gboolean
+ostree_repo_reload_config (OstreeRepo *self,
+                           GCancellable *cancellable,
+                           GError **error);
+

By default, an OstreeRepo will cache the remote configuration and its +own repo/config data. This API can be used to reload it.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

repo

 

cancellable

cancellable

 

error

error

 
+
+

Since: 2017.2

+
+
+
+

ostree_repo_get_remote_boolean_option ()

+
gboolean
+ostree_repo_get_remote_boolean_option (OstreeRepo *self,
+                                       const char *remote_name,
+                                       const char *option_name,
+                                       gboolean default_value,
+                                       gboolean *out_value,
+                                       GError **error);
+

OSTree remotes are represented by keyfile groups, formatted like: +[remote "remotename"]. This function returns a value named option_name + +underneath that group, and returns it as a boolean. +If the option is not set, out_value + will be set to default_value +. If an +error is returned, out_value + will be set to FALSE.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

A OstreeRepo

 

remote_name

Name

 

option_name

Option

 

default_value

Value returned if option_name +is not present

 

out_value

(out) : location to store the result.

 

error

Error

 
+
+
+

Returns

+

TRUE on success, otherwise FALSE with error +set

+
+

Since: 2016.5

+
+
+
+

ostree_repo_get_remote_list_option ()

+
gboolean
+ostree_repo_get_remote_list_option (OstreeRepo *self,
+                                    const char *remote_name,
+                                    const char *option_name,
+                                    char ***out_value,
+                                    GError **error);
+

OSTree remotes are represented by keyfile groups, formatted like: +[remote "remotename"]. This function returns a value named option_name + +underneath that group, and returns it as a zero terminated array of strings. +If the option is not set, or if an error is returned, out_value + will be set +to NULL.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

A OstreeRepo

 

remote_name

Name

 

option_name

Option

 

out_value

location to store the list +of strings. The list should be freed with +g_strfreev().

[out][array zero-terminated=1]

error

Error

 
+
+
+

Returns

+

TRUE on success, otherwise FALSE with error +set

+
+

Since: 2016.5

+
+
+
+

ostree_repo_get_remote_option ()

+
gboolean
+ostree_repo_get_remote_option (OstreeRepo *self,
+                               const char *remote_name,
+                               const char *option_name,
+                               const char *default_value,
+                               char **out_value,
+                               GError **error);
+

OSTree remotes are represented by keyfile groups, formatted like: +[remote "remotename"]. This function returns a value named option_name + +underneath that group, or default_value + if the remote exists but not the +option name. If an error is returned, out_value + will be set to NULL.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

A OstreeRepo

 

remote_name

Name

 

option_name

Option

 

default_value

Value returned if option_name +is not present.

[nullable]

out_value

Return location for value.

[out][nullable]

error

Error

 
+
+
+

Returns

+

TRUE on success, otherwise FALSE with error +set

+
+

Since: 2016.5

+
+
+
+

ostree_repo_get_parent ()

+
OstreeRepo *
+ostree_repo_get_parent (OstreeRepo *self);
+

Before this function can be used, ostree_repo_init() must have been +called.

+
+

Parameters

+
+++++ + + + + + +

self

Repo

 
+
+
+

Returns

+

Parent repository, or NULL if none.

+

[transfer none][nullable]

+
+
+
+
+

ostree_repo_write_config ()

+
gboolean
+ostree_repo_write_config (OstreeRepo *self,
+                          GKeyFile *new_config,
+                          GError **error);
+

Save new_config + in place of this repository's config file.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Repo

 

new_config

Overwrite the config file with this data

 

error

a GError

 
+
+
+
+
+

ostree_repo_scan_hardlinks ()

+
gboolean
+ostree_repo_scan_hardlinks (OstreeRepo *self,
+                            GCancellable *cancellable,
+                            GError **error);
+

This function is deprecated in favor of using ostree_repo_devino_cache_new(), +which allows a precise mapping to be built up between hardlink checkout files +and their checksums between ostree_repo_checkout_at() and +ostree_repo_write_directory_to_mtree().

+

When invoking ostree_repo_write_directory_to_mtree(), it has to compute the +checksum of all files. If your commit contains hardlinks from a checkout, +this functions builds a mapping of device numbers and inodes to their +checksum.

+

There is an upfront cost to creating this mapping, as this will scan the +entire objects directory. If your commit is composed of mostly hardlinks to +existing ostree objects, then this will speed up considerably, so call it +before you call ostree_repo_write_directory_to_mtree() or similar. However, +ostree_repo_devino_cache_new() is better as it avoids scanning all objects.

+

Multithreading: This function is *not* MT safe.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_prepare_transaction ()

+
gboolean
+ostree_repo_prepare_transaction (OstreeRepo *self,
+                                 gboolean *out_transaction_resume,
+                                 GCancellable *cancellable,
+                                 GError **error);
+

Starts or resumes a transaction. In order to write to a repo, you +need to start a transaction. You can complete the transaction with +ostree_repo_commit_transaction(), or abort the transaction with +ostree_repo_abort_transaction().

+

Currently, transactions may result in partial commits or data in the target +repository if interrupted during ostree_repo_commit_transaction(), and +further writing refs is also not currently atomic.

+

There can be at most one transaction active on a repo at a time per instance +of OstreeRepo; however, it is safe to have multiple threads writing objects +on a single OstreeRepo instance as long as their lifetime is bounded by the +transaction.

+

Locking: Acquires a shared lock; release via commit or abort +Multithreading: This function is *not* MT safe; only one transaction can be +active at a time.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

out_transaction_resume

Whether this transaction +is resuming from a previous one. This is a legacy state, now OSTree +pulls use per-commit state/.commitpartial files.

[allow-none][out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_commit_transaction ()

+
gboolean
+ostree_repo_commit_transaction (OstreeRepo *self,
+                                OstreeRepoTransactionStats *out_stats,
+                                GCancellable *cancellable,
+                                GError **error);
+

Complete the transaction. Any refs set with +ostree_repo_transaction_set_ref() or +ostree_repo_transaction_set_refspec() will be written out.

+

Note that if multiple threads are performing writes, all such threads must +have terminated before this function is invoked.

+

Locking: Releases shared lock acquired by ostree_repo_prepare_transaction() +Multithreading: This function is *not* MT safe; only one transaction can be +active at a time.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

out_stats

A set of statistics of things +that happened during this transaction.

[allow-none][out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_abort_transaction ()

+
gboolean
+ostree_repo_abort_transaction (OstreeRepo *self,
+                               GCancellable *cancellable,
+                               GError **error);
+

Abort the active transaction; any staged objects and ref changes will be +discarded. You *must* invoke this if you have chosen not to invoke +ostree_repo_commit_transaction(). Calling this function when not in a +transaction will do nothing and return successfully.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_transaction_set_refspec ()

+
void
+ostree_repo_transaction_set_refspec (OstreeRepo *self,
+                                     const char *refspec,
+                                     const char *checksum);
+

Like ostree_repo_transaction_set_ref(), but takes concatenated +refspec + format as input instead of separate remote and name +arguments.

+

Multithreading: Since v2017.15 this function is MT safe.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

refspec

The refspec to write

 

checksum

The checksum to point it to.

[nullable]
+
+
+
+
+

ostree_repo_transaction_set_collection_ref ()

+
void
+ostree_repo_transaction_set_collection_ref
+                               (OstreeRepo *self,
+                                const OstreeCollectionRef *ref,
+                                const char *checksum);
+

If checksum + is not NULL, then record it as the target of local ref named +ref +.

+

Otherwise, if checksum + is NULL, then record that the ref should +be deleted.

+

The change will not be written out immediately, but when the transaction +is completed with ostree_repo_commit_transaction(). If the transaction +is instead aborted with ostree_repo_abort_transaction(), no changes will +be made to the repository.

+

Multithreading: Since v2017.15 this function is MT safe.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

ref

The collection–ref to write

 

checksum

The checksum to point it to.

[nullable]
+
+

Since: 2018.6

+
+
+
+

ostree_repo_transaction_set_ref ()

+
void
+ostree_repo_transaction_set_ref (OstreeRepo *self,
+                                 const char *remote,
+                                 const char *ref,
+                                 const char *checksum);
+

If checksum + is not NULL, then record it as the target of ref named +ref +; if remote + is provided, the ref will appear to originate from that +remote.

+

Otherwise, if checksum + is NULL, then record that the ref should +be deleted.

+

The change will be written when the transaction is completed with +ostree_repo_commit_transaction(); that function takes care of writing all of +the objects (such as the commit referred to by checksum +) before updating the +refs. If the transaction is instead aborted with +ostree_repo_abort_transaction(), no changes to the ref will be made to the +repository.

+

Note however that currently writing *multiple* refs is not truly atomic; if +the process or system is terminated during +ostree_repo_commit_transaction(), it is possible that just some of the refs +will have been updated. Your application should take care to handle this +case.

+

Multithreading: Since v2017.15 this function is MT safe.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

remote

A remote for the ref.

[allow-none]

ref

The ref to write

 

checksum

The checksum to point it to.

[nullable]
+
+
+
+
+

ostree_repo_set_ref_immediate ()

+
gboolean
+ostree_repo_set_ref_immediate (OstreeRepo *self,
+                               const char *remote,
+                               const char *ref,
+                               const char *checksum,
+                               GCancellable *cancellable,
+                               GError **error);
+

This is like ostree_repo_transaction_set_ref(), except it may be +invoked outside of a transaction. This is presently safe for the +case where we're creating or overwriting an existing ref.

+

Multithreading: This function is MT safe.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

remote

A remote for the ref.

[allow-none]

ref

The ref to write

 

checksum

The checksum to point it to, or NULL to unset.

[allow-none]

cancellable

GCancellable

 

error

GError

 
+
+
+
+
+

ostree_repo_set_alias_ref_immediate ()

+
gboolean
+ostree_repo_set_alias_ref_immediate (OstreeRepo *self,
+                                     const char *remote,
+                                     const char *ref,
+                                     const char *target,
+                                     GCancellable *cancellable,
+                                     GError **error);
+

Like ostree_repo_set_ref_immediate(), but creates an alias.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

remote

A remote for the ref.

[allow-none]

ref

The ref to write

 

target

The ref target to point it to, or NULL to unset.

[allow-none]

cancellable

GCancellable

 

error

GError

 
+
+

Since: 2017.10

+
+
+
+

ostree_repo_set_cache_dir ()

+
gboolean
+ostree_repo_set_cache_dir (OstreeRepo *self,
+                           int dfd,
+                           const char *path,
+                           GCancellable *cancellable,
+                           GError **error);
+

Set a custom location for the cache directory used for e.g. +per-remote summary caches. Setting this manually is useful when +doing operations on a system repo as a user because you don't have +write permissions in the repo, where the cache is normally stored.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

dfd

directory fd

 

path

subpath in dfd +

 

cancellable

a GCancellable

 

error

a GError

 
+
+

Since: 2016.5

+
+
+
+

ostree_repo_set_collection_id ()

+
gboolean
+ostree_repo_set_collection_id (OstreeRepo *self,
+                               const gchar *collection_id,
+                               GError **error);
+

Set or clear the collection ID of this repository. See collection IDs. +The update will be made in memory, but must be written out to the repository +configuration on disk using ostree_repo_write_config().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeRepo

 

collection_id

new collection ID, or NULL to unset it.

[nullable]

error

return location for a GError, or NULL

 
+
+
+

Returns

+

TRUE on success, FALSE otherwise

+
+

Since: 2018.6

+
+
+
+

ostree_repo_set_collection_ref_immediate ()

+
gboolean
+ostree_repo_set_collection_ref_immediate
+                               (OstreeRepo *self,
+                                const OstreeCollectionRef *ref,
+                                const char *checksum,
+                                GCancellable *cancellable,
+                                GError **error);
+

This is like ostree_repo_transaction_set_collection_ref(), except it may be +invoked outside of a transaction. This is presently safe for the +case where we're creating or overwriting an existing ref.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

ref

The collection–ref to write

 

checksum

The checksum to point it to, or NULL to unset.

[nullable]

cancellable

GCancellable

 

error

GError

 
+
+
+

Returns

+

TRUE on success, FALSE otherwise

+
+

Since: 2018.6

+
+
+
+

ostree_repo_sign_delta ()

+
gboolean
+ostree_repo_sign_delta (OstreeRepo *self,
+                        const gchar *from_commit,
+                        const gchar *to_commit,
+                        const gchar *key_id,
+                        const gchar *homedir,
+                        GCancellable *cancellable,
+                        GError **error);
+

This function is deprecated, sign the summary file instead. +Add a GPG signature to a static delta.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

from_commit

From commit

 

to_commit

To commit

 

key_id

key id

 

homedir

homedir

 

cancellable

cancellable

 

error

error

 
+
+
+
+
+

ostree_repo_has_object ()

+
gboolean
+ostree_repo_has_object (OstreeRepo *self,
+                        OstreeObjectType objtype,
+                        const char *checksum,
+                        gboolean *out_have_object,
+                        GCancellable *cancellable,
+                        GError **error);
+

Set out_have_object + to TRUE if self + contains the given object; +FALSE otherwise.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

checksum

ASCII SHA256 checksum

 

out_have_object

TRUE if repository contains object.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

FALSE if an unexpected error occurred, TRUE otherwise

+
+
+
+
+

ostree_repo_mark_commit_partial ()

+
gboolean
+ostree_repo_mark_commit_partial (OstreeRepo *self,
+                                 const char *checksum,
+                                 gboolean is_partial,
+                                 GError **error);
+

Commits in the "partial" state do not have all their child objects +written. This occurs in various situations, such as during a pull, +but also if a "subpath" pull is used, as well as "commit only" +pulls.

+

This function is used by ostree_repo_pull_with_options(); you +should use this if you are implementing a different type of transport.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

checksum

Commit SHA-256

 

is_partial

Whether or not this commit is partial

 

error

Error

 
+
+

Since: 2017.15

+
+
+
+

ostree_repo_mark_commit_partial_reason ()

+
gboolean
+ostree_repo_mark_commit_partial_reason
+                               (OstreeRepo *self,
+                                const char *checksum,
+                                gboolean is_partial,
+                                OstreeRepoCommitState in_state,
+                                GError **error);
+

Allows the setting of a reason code for a partial commit. Presently +it only supports setting reason bitmask to +OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL, or +OSTREE_REPO_COMMIT_STATE_NORMAL. This will allow successive ostree +fsck operations to exit properly with an error code if the +repository has been truncated as a result of fsck trying to repair +it.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

checksum

Commit SHA-256

 

is_partial

Whether or not this commit is partial

 

in_state

Reason bitmask for partial commit

 

error

Error

 
+
+

Since: 2019.4

+
+
+
+

ostree_repo_write_metadata ()

+
gboolean
+ostree_repo_write_metadata (OstreeRepo *self,
+                            OstreeObjectType objtype,
+                            const char *expected_checksum,
+                            GVariant *object,
+                            guchar **out_csum,
+                            GCancellable *cancellable,
+                            GError **error);
+

Store the metadata object object +. Return the checksum +as out_csum +.

+

If expected_checksum + is not NULL, verify it against the +computed checksum.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

expected_checksum

If provided, validate content against this checksum.

[nullable]

object

Metadata

 

out_csum

Binary checksum.

[out][array fixed-size=32][optional]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_metadata_async ()

+
void
+ostree_repo_write_metadata_async (OstreeRepo *self,
+                                  OstreeObjectType objtype,
+                                  const char *expected_checksum,
+                                  GVariant *object,
+                                  GCancellable *cancellable,
+                                  GAsyncReadyCallback callback,
+                                  gpointer user_data);
+

Asynchronously store the metadata object variant +. If provided, +the checksum expected_checksum + will be verified.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

expected_checksum

If provided, validate content against this checksum.

[nullable]

object

Metadata

 

cancellable

Cancellable

 

callback

Invoked when metadata is writed

 

user_data

Data for callback +

 
+
+
+
+
+

ostree_repo_write_metadata_finish ()

+
gboolean
+ostree_repo_write_metadata_finish (OstreeRepo *self,
+                                   GAsyncResult *result,
+                                   guchar **out_csum,
+                                   GError **error);
+

Complete a call to ostree_repo_write_metadata_async().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

result

Result

 

out_csum

Binary checksum value.

[out][array fixed-size=32][element-type guint8]

error

Error

 
+
+
+
+
+

ostree_repo_write_content ()

+
gboolean
+ostree_repo_write_content (OstreeRepo *self,
+                           const char *expected_checksum,
+                           GInputStream *object_input,
+                           guint64 length,
+                           guchar **out_csum,
+                           GCancellable *cancellable,
+                           GError **error);
+

Store the content object streamed as object_input +, +with total length length +. The actual checksum will +be returned as out_csum +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

expected_checksum

If provided, validate content against this checksum.

[allow-none]

object_input

Content object stream

 

length

Length of object_input +

 

out_csum

Binary checksum.

[out][array fixed-size=32][optional][nullable]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_regfile ()

+
OstreeContentWriter *
+ostree_repo_write_regfile (OstreeRepo *self,
+                           const char *expected_checksum,
+                           guint32 uid,
+                           guint32 gid,
+                           guint32 mode,
+                           guint64 content_len,
+                           GVariant *xattrs,
+                           GError **error);
+

Create an OstreeContentWriter that allows streaming output into +the repository.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo,

 

expected_checksum

Expected checksum (SHA-256 hex string).

[allow-none]

uid

user id

 

gid

group id

 

mode

Unix file mode

 

content_len

Expected content length

 

xattrs

Extended attributes (GVariant type (ayay)).

[allow-none]

error

Error

 
+
+
+

Returns

+

A new writer, or NULL on error.

+

[transfer full]

+
+

Since: 2021.2

+
+
+
+

ostree_repo_write_regfile_inline ()

+
char *
+ostree_repo_write_regfile_inline (OstreeRepo *self,
+                                  const char *expected_checksum,
+                                  guint32 uid,
+                                  guint32 gid,
+                                  guint32 mode,
+                                  GVariant *xattrs,
+                                  const guint8 *buf,
+                                  gsize len,
+                                  GCancellable *cancellable,
+                                  GError **error);
+

Synchronously create a file object from the provided content. This API +is intended for small files where it is reasonable to buffer the entire +content in memory.

+

Unlike ostree_repo_write_content(), if expected_checksum + is provided, +this function will not check for the presence of the object beforehand.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

repo

 

expected_checksum

The expected checksum.

[allow-none]

uid

User id

 

gid

Group id

 

mode

File mode

 

xattrs

Extended attributes, GVariant of type (ayay).

[allow-none]

buf

File contents.

[array length=len][element-type guint8]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

Checksum (as a hex string) of the committed file.

+

[transfer full]

+
+

Since: 2021.2

+
+
+
+

ostree_repo_write_symlink ()

+
char *
+ostree_repo_write_symlink (OstreeRepo *self,
+                           const char *expected_checksum,
+                           guint32 uid,
+                           guint32 gid,
+                           GVariant *xattrs,
+                           const char *symlink_target,
+                           GCancellable *cancellable,
+                           GError **error);
+

Synchronously create a symlink object.

+

Unlike ostree_repo_write_content(), if expected_checksum + is provided, +this function will not check for the presence of the object beforehand.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

repo

 

expected_checksum

The expected checksum.

[allow-none]

uid

User id

 

gid

Group id

 

xattrs

Extended attributes, GVariant of type (ayay).

[allow-none]

symlink_target

Target of the symbolic link

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

Checksum (as a hex string) of the committed file.

+

[transfer full]

+
+

Since: 2021.2

+
+
+
+

ostree_repo_write_metadata_trusted ()

+
gboolean
+ostree_repo_write_metadata_trusted (OstreeRepo *self,
+                                    OstreeObjectType objtype,
+                                    const char *checksum,
+                                    GVariant *variant,
+                                    GCancellable *cancellable,
+                                    GError **error);
+

Store the metadata object variant +; the provided checksum + is +trusted.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

checksum

Store object with this ASCII SHA256 checksum

 

variant

Metadata object

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_metadata_stream_trusted ()

+
gboolean
+ostree_repo_write_metadata_stream_trusted
+                               (OstreeRepo *self,
+                                OstreeObjectType objtype,
+                                const char *checksum,
+                                GInputStream *object_input,
+                                guint64 length,
+                                GCancellable *cancellable,
+                                GError **error);
+

Store the metadata object variant +; the provided checksum + is +trusted.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

checksum

Store object with this ASCII SHA256 checksum

 

object_input

Metadata object stream

 

length

Length, may be 0 for unknown

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_content_trusted ()

+
gboolean
+ostree_repo_write_content_trusted (OstreeRepo *self,
+                                   const char *checksum,
+                                   GInputStream *object_input,
+                                   guint64 length,
+                                   GCancellable *cancellable,
+                                   GError **error);
+

Store the content object streamed as object_input +, with total +length length +. The given checksum + will be treated as trusted.

+

This function should be used when importing file objects from local +disk, for example.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

checksum

Store content using this ASCII SHA256 checksum

 

object_input

Content stream

 

length

Length of object_input +

 

cancellable

Cancellable

 

error

Data for callback +

 
+
+
+
+
+

ostree_repo_write_content_async ()

+
void
+ostree_repo_write_content_async (OstreeRepo *self,
+                                 const char *expected_checksum,
+                                 GInputStream *object,
+                                 guint64 length,
+                                 GCancellable *cancellable,
+                                 GAsyncReadyCallback callback,
+                                 gpointer user_data);
+

Asynchronously store the content object object +. If provided, the +checksum expected_checksum + will be verified.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

expected_checksum

If provided, validate content against this checksum.

[allow-none]

object

Input

 

length

Length of object +

 

cancellable

Cancellable

 

callback

Invoked when content is writed

 

user_data

User data for callback +

 
+
+
+
+
+

ostree_repo_write_content_finish ()

+
gboolean
+ostree_repo_write_content_finish (OstreeRepo *self,
+                                  GAsyncResult *result,
+                                  guchar **out_csum,
+                                  GError **error);
+

Completes an invocation of ostree_repo_write_content_async().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

a OstreeRepo

 

result

a GAsyncResult

 

out_csum

A binary SHA256 +checksum of the content object.

[out][transfer full][optional]

error

a GError

 
+
+
+
+
+

ostree_repo_resolve_rev ()

+
gboolean
+ostree_repo_resolve_rev (OstreeRepo *self,
+                         const char *refspec,
+                         gboolean allow_noent,
+                         char **out_rev,
+                         GError **error);
+

Look up the given refspec, returning the checksum it references in +the parameter out_rev +. Will fall back on remote directory if cannot +find the given refspec in local.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

refspec

A refspec

 

allow_noent

Do not throw an error if refspec does not exist

 

out_rev

A checksum,or NULL if allow_noent +is true and it +does not exist.

[out][nullable][transfer full]

error

Error

 
+
+
+
+
+

ostree_repo_resolve_rev_ext ()

+
gboolean
+ostree_repo_resolve_rev_ext (OstreeRepo *self,
+                             const char *refspec,
+                             gboolean allow_noent,
+                             OstreeRepoResolveRevExtFlags flags,
+                             char **out_rev,
+                             GError **error);
+

Look up the given refspec, returning the checksum it references in +the parameter out_rev +. Differently from ostree_repo_resolve_rev(), +this will not fall back to searching through remote repos if a +local ref is specified but not found.

+

The flag OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY is implied so +using it has no effect.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

refspec

A refspec

 

allow_noent

Do not throw an error if refspec does not exist

 

flags

Options controlling behavior

 

out_rev

A checksum,or NULL if allow_noent +is true and it +does not exist.

[out][nullable][transfer full]

error

Error

 
+
+

Since: 2016.7

+
+
+
+

ostree_repo_list_refs ()

+
gboolean
+ostree_repo_list_refs (OstreeRepo *self,
+                       const char *refspec_prefix,
+                       GHashTable **out_all_refs,
+                       GCancellable *cancellable,
+                       GError **error);
+

If refspec_prefix + is NULL, list all local and remote refspecs, +with their current values in out_all_refs +. Otherwise, only list +refspecs which have refspec_prefix + as a prefix.

+

out_all_refs + will be returned as a mapping from refspecs (including the +remote name) to checksums. If refspec_prefix + is non-NULL, it will be +removed as a prefix from the hash table keys.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

refspec_prefix

Only list refs which match this prefix.

[allow-none]

out_all_refs

Mapping from refspec to checksum.

[out][element-type utf8 utf8][transfer container]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_list_refs_ext ()

+
gboolean
+ostree_repo_list_refs_ext (OstreeRepo *self,
+                           const char *refspec_prefix,
+                           GHashTable **out_all_refs,
+                           OstreeRepoListRefsExtFlags flags,
+                           GCancellable *cancellable,
+                           GError **error);
+

If refspec_prefix + is NULL, list all local and remote refspecs, +with their current values in out_all_refs +. Otherwise, only list +refspecs which have refspec_prefix + as a prefix.

+

out_all_refs + will be returned as a mapping from refspecs (including the +remote name) to checksums. Differently from ostree_repo_list_refs(), the +refspec_prefix + will not be removed from the refspecs in the hash table.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

refspec_prefix

Only list refs which match this prefix.

[allow-none]

out_all_refs

Mapping from refspec to checksum.

[out][element-type utf8 utf8][transfer container]

flags

Options controlling listing behavior

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2016.4

+
+
+
+

ostree_repo_list_collection_refs ()

+
gboolean
+ostree_repo_list_collection_refs (OstreeRepo *self,
+                                  const char *match_collection_id,
+                                  GHashTable **out_all_refs,
+                                  OstreeRepoListRefsExtFlags flags,
+                                  GCancellable *cancellable,
+                                  GError **error);
+

List all local, mirrored, and remote refs, mapping them to the commit +checksums they currently point to in out_all_refs +. If match_collection_id + +is specified, the results will be limited to those with an equal collection +ID.

+

OstreeCollectionRefs are guaranteed to be returned with their collection ID +set to a non-NULL value; so no refs from refs/heads will be listed if no +collection ID is configured for the repository +(ostree_repo_get_collection_id()).

+

If you want to exclude refs from refs/remotes, use +OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES in flags +. Similarly use +OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS to exclude refs from +refs/mirrors.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

match_collection_id

If non-NULL, only list refs from this collection.

[nullable]

out_all_refs

Mapping from collection–ref to checksum.

[out][element-type OstreeCollectionRef utf8][transfer container]

flags

Options controlling listing behavior

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

TRUE on success, FALSE otherwise

+
+

Since: 2018.6

+
+
+
+

ostree_repo_remote_list_refs ()

+
gboolean
+ostree_repo_remote_list_refs (OstreeRepo *self,
+                              const char *remote_name,
+                              GHashTable **out_all_refs,
+                              GCancellable *cancellable,
+                              GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

remote_name

Name of the remote.

 

out_all_refs

Mapping from ref to checksum.

[out][element-type utf8 utf8][transfer container]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_resolve_collection_ref ()

+
gboolean
+ostree_repo_resolve_collection_ref (OstreeRepo *self,
+                                    const OstreeCollectionRef *ref,
+                                    gboolean allow_noent,
+                                    OstreeRepoResolveRevExtFlags flags,
+                                    char **out_rev,
+                                    GCancellable *cancellable,
+                                    GError **error);
+

Look up the checksum for the given collection–ref, returning it in out_rev +. +This will search through the mirrors and remote refs.

+

If allow_noent + is TRUE and the given ref + cannot be found, TRUE will be +returned and out_rev + will be set to NULL. If allow_noent + is FALSE and +the given ref + cannot be found, a G_IO_ERROR_NOT_FOUND error will be +returned.

+

If you want to check only local refs, not remote or mirrored ones, use the +flag OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY. This is analogous to using +ostree_repo_resolve_rev_ext() but for collection-refs.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeRepo

 

ref

a collection–ref to resolve

 

allow_noent

TRUE to not throw an error if ref +doesn’t exist

 

flags

options controlling behaviour

 

out_rev

return location for +the checksum corresponding to ref +, or NULL if allow_noent +is TRUE and +the ref +could not be found.

[out][transfer full][optional][nullable]

cancellable

a GCancellable, or NULL.

[nullable]

error

return location for a GError, or NULL

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+

Since: 2018.6

+
+
+
+

ostree_repo_load_variant ()

+
gboolean
+ostree_repo_load_variant (OstreeRepo *self,
+                          OstreeObjectType objtype,
+                          const char *sha256,
+                          GVariant **out_variant,
+                          GError **error);
+

Load the metadata object sha256 + of type objtype +, storing the +result in out_variant +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Expected object type

 

sha256

Checksum string

 

out_variant

Metadata object.

[out][transfer full]

error

Error

 
+
+
+
+
+

ostree_repo_load_commit ()

+
gboolean
+ostree_repo_load_commit (OstreeRepo *self,
+                         const char *checksum,
+                         GVariant **out_commit,
+                         OstreeRepoCommitState *out_state,
+                         GError **error);
+

A version of ostree_repo_load_variant() specialized to commits, +capable of returning extended state information. Currently +the only extended state is OSTREE_REPO_COMMIT_STATE_PARTIAL, which +means that only a sub-path of the commit is available.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

checksum

Commit checksum

 

out_commit

Commit.

[out][allow-none]

out_state

Commit state.

[out][allow-none]

error

Error

 
+
+
+
+
+

ostree_repo_load_variant_if_exists ()

+
gboolean
+ostree_repo_load_variant_if_exists (OstreeRepo *self,
+                                    OstreeObjectType objtype,
+                                    const char *sha256,
+                                    GVariant **out_variant,
+                                    GError **error);
+

Attempt to load the metadata object sha256 + of type objtype + if it +exists, storing the result in out_variant +. If it doesn't exist, +out_variant + will be set to NULL and the function will still +return TRUE.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

sha256

ASCII checksum

 

out_variant

Metadata.

[out][nullable][transfer full]

error

Error

 
+
+
+
+
+

ostree_repo_load_file ()

+
gboolean
+ostree_repo_load_file (OstreeRepo *self,
+                       const char *checksum,
+                       GInputStream **out_input,
+                       GFileInfo **out_file_info,
+                       GVariant **out_xattrs,
+                       GCancellable *cancellable,
+                       GError **error);
+

Load content object, decomposing it into three parts: the actual +content (for regular files), the metadata, and extended attributes.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

checksum

ASCII SHA256 checksum

 

out_input

File content.

[out][optional][nullable]

out_file_info

File information.

[out][optional][nullable]

out_xattrs

Extended attributes.

[out][optional][nullable]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_load_object_stream ()

+
gboolean
+ostree_repo_load_object_stream (OstreeRepo *self,
+                                OstreeObjectType objtype,
+                                const char *checksum,
+                                GInputStream **out_input,
+                                guint64 *out_size,
+                                GCancellable *cancellable,
+                                GError **error);
+

Load object as a stream; useful when copying objects between +repositories.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

checksum

ASCII SHA256 checksum

 

out_input

Stream for object.

[out]

out_size

Length of out_input +.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_query_object_storage_size ()

+
gboolean
+ostree_repo_query_object_storage_size (OstreeRepo *self,
+                                       OstreeObjectType objtype,
+                                       const char *sha256,
+                                       guint64 *out_size,
+                                       GCancellable *cancellable,
+                                       GError **error);
+

Return the size in bytes of object with checksum sha256 +, after any +compression has been applied.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

sha256

Checksum

 

out_size

Size in bytes object occupies physically.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_import_object_from ()

+
gboolean
+ostree_repo_import_object_from (OstreeRepo *self,
+                                OstreeRepo *source,
+                                OstreeObjectType objtype,
+                                const char *checksum,
+                                GCancellable *cancellable,
+                                GError **error);
+

Copy object named by objtype + and checksum + into self + from the +source repository source +. If both repositories are of the same +type and on the same filesystem, this will simply be a fast Unix +hard link operation.

+

Otherwise, a copy will be performed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Destination repo

 

source

Source repo

 

objtype

Object type

 

checksum

checksum

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_import_object_from_with_trust ()

+
gboolean
+ostree_repo_import_object_from_with_trust
+                               (OstreeRepo *self,
+                                OstreeRepo *source,
+                                OstreeObjectType objtype,
+                                const char *checksum,
+                                gboolean trusted,
+                                GCancellable *cancellable,
+                                GError **error);
+

Copy object named by objtype + and checksum + into self + from the +source repository source +. If trusted + is TRUE and both +repositories are of the same type and on the same filesystem, +this will simply be a fast Unix hard link operation.

+

Otherwise, a copy will be performed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Destination repo

 

source

Source repo

 

objtype

Object type

 

checksum

checksum

 

trusted

If TRUE, assume the source repo is valid and trusted

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2016.5

+
+
+
+

ostree_repo_import_archive_to_mtree ()

+
gboolean
+ostree_repo_import_archive_to_mtree (OstreeRepo *self,
+                                     OstreeRepoImportArchiveOptions *opts,
+                                     void *archive,
+                                     OstreeMutableTree *mtree,
+                                     OstreeRepoCommitModifier *modifier,
+                                     GCancellable *cancellable,
+                                     GError **error);
+

Import an archive file archive + into the repository, and write its +file structure to mtree +.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

opts

Options structure, ensure this is zeroed, then set specific variables

 

archive

Really this is "struct archive*"

 

mtree

The OstreeMutableTree to write to

 

modifier

Optional commit modifier.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_export_tree_to_archive ()

+
gboolean
+ostree_repo_export_tree_to_archive (OstreeRepo *self,
+                                    OstreeRepoExportArchiveOptions *opts,
+                                    OstreeRepoFile *root,
+                                    void *archive,
+                                    GCancellable *cancellable,
+                                    GError **error);
+

Import an archive file archive + into the repository, and write its +file structure to mtree +.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

opts

Options controlling conversion

 

root

An OstreeRepoFile for the base directory

 

archive

A struct archive, but specified as void to avoid a dependency on the libarchive +headers

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_delete_object ()

+
gboolean
+ostree_repo_delete_object (OstreeRepo *self,
+                           OstreeObjectType objtype,
+                           const char *sha256,
+                           GCancellable *cancellable,
+                           GError **error);
+

Remove the object of type objtype + with checksum sha256 + +from the repository. An error of type G_IO_ERROR_NOT_FOUND +is thrown if the object does not exist.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

sha256

Checksum

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_fsck_object ()

+
gboolean
+ostree_repo_fsck_object (OstreeRepo *self,
+                         OstreeObjectType objtype,
+                         const char *sha256,
+                         GCancellable *cancellable,
+                         GError **error);
+

Verify consistency of the object; this performs checks only relevant to the +immediate object itself, such as checksumming. This API call will not itself +traverse metadata objects for example.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

objtype

Object type

 

sha256

Checksum

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2017.15

+
+
+
+

OstreeRepoCommitFilter ()

+
OstreeRepoCommitFilterResult
+(*OstreeRepoCommitFilter) (OstreeRepo *repo,
+                           const char *path,
+                           GFileInfo *file_info,
+                           gpointer user_data);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

repo

Repo

 

path

Path to file

 

file_info

File information

 

user_data

User data

 
+
+
+

Returns

+

OstreeRepoCommitFilterResult saying whether or not to commit this file

+
+
+
+
+

ostree_repo_commit_modifier_new ()

+
OstreeRepoCommitModifier *
+ostree_repo_commit_modifier_new (OstreeRepoCommitModifierFlags flags,
+                                 OstreeRepoCommitFilter commit_filter,
+                                 gpointer user_data,
+                                 GDestroyNotify destroy_notify);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

flags

Control options for filter

 

commit_filter

Function that can inspect individual files.

[allow-none]

user_data

User data.

[allow-none]

destroy_notify

A GDestroyNotify

 
+
+
+

Returns

+

A new commit modifier.

+

[transfer full]

+
+
+
+
+

OstreeRepoCommitModifierXattrCallback ()

+
GVariant *
+(*OstreeRepoCommitModifierXattrCallback)
+                               (OstreeRepo *repo,
+                                const char *path,
+                                GFileInfo *file_info,
+                                gpointer user_data);
+
+
+
+

ostree_repo_commit_modifier_set_xattr_callback ()

+
void
+ostree_repo_commit_modifier_set_xattr_callback
+                               (OstreeRepoCommitModifier *modifier,
+                                OstreeRepoCommitModifierXattrCallback callback,
+                                GDestroyNotify destroy,
+                                gpointer user_data);
+

If set, this function should return extended attributes to use for +the given path. This is useful for things like ACLs and SELinux, +where a build system can label the files as it's committing to the +repository.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

modifier

An OstreeRepoCommitModifier

 

callback

Function to be invoked, should return extended attributes for path

 

destroy

Destroy notification

 

user_data

Data for callback +:

 
+
+
+
+
+

ostree_repo_commit_modifier_set_sepolicy ()

+
void
+ostree_repo_commit_modifier_set_sepolicy
+                               (OstreeRepoCommitModifier *modifier,
+                                OstreeSePolicy *sepolicy);
+

If policy + is non-NULL, use it to look up labels to use for +"security.selinux" extended attributes.

+

Note that any policy specified this way operates in addition to any +extended attributes provided via +ostree_repo_commit_modifier_set_xattr_callback(). However if both +specify a value for "security.selinux", then the one from the +policy wins.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

modifier

An OstreeRepoCommitModifier

 

sepolicy

Policy to use for labeling.

[allow-none]
+
+
+
+
+

ostree_repo_commit_modifier_set_sepolicy_from_commit ()

+
gboolean
+ostree_repo_commit_modifier_set_sepolicy_from_commit
+                               (OstreeRepoCommitModifier *modifier,
+                                OstreeRepo *repo,
+                                const char *rev,
+                                GCancellable *cancellable,
+                                GError **error);
+

In many cases, one wants to create a "derived" commit from base commit. +SELinux policy labels are part of that base commit. This API allows +one to easily set up SELinux labeling from a base commit.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

modifier

Commit modifier

 

repo

OSTree repo containing rev +

 

rev

Find SELinux policy from this base commit

 
+
+

Since: 2020.4

+
+
+
+

ostree_repo_commit_modifier_set_devino_cache ()

+
void
+ostree_repo_commit_modifier_set_devino_cache
+                               (OstreeRepoCommitModifier *modifier,
+                                OstreeRepoDevInoCache *cache);
+

See the documentation for +ostree_repo_devino_cache_new(). This function can +then be used for later calls to +ostree_repo_write_directory_to_mtree() to optimize commits.

+

Note if your process has multiple writers, you should use separate +OSTreeRepo instances if you want to also use this API.

+

This function will add a reference to cache + without copying - you +should avoid further mutation of the cache.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

modifier

Modifier

 

cache

A hash table caching device,inode to checksums

 
+
+

Since: 2017.13

+
+
+
+

ostree_repo_commit_modifier_ref ()

+
OstreeRepoCommitModifier *
+ostree_repo_commit_modifier_ref (OstreeRepoCommitModifier *modifier);
+
+
+
+

ostree_repo_commit_modifier_unref ()

+
void
+ostree_repo_commit_modifier_unref (OstreeRepoCommitModifier *modifier);
+
+
+
+

ostree_repo_devino_cache_new ()

+
OstreeRepoDevInoCache *
+ostree_repo_devino_cache_new (void);
+

OSTree has support for pairing ostree_repo_checkout_tree_at() using +hardlinks in combination with a later +ostree_repo_write_directory_to_mtree() using a (normally modified) +directory. In order for OSTree to optimally detect just the new +files, use this function and fill in the devino_to_csum_cache +member of OstreeRepoCheckoutAtOptions, then call +ostree_repo_commit_set_devino_cache().

+
+

Returns

+

Newly allocated cache.

+

[transfer full]

+
+
+
+
+

ostree_repo_devino_cache_ref ()

+
OstreeRepoDevInoCache *
+ostree_repo_devino_cache_ref (OstreeRepoDevInoCache *cache);
+
+
+
+

ostree_repo_devino_cache_unref ()

+
void
+ostree_repo_devino_cache_unref (OstreeRepoDevInoCache *cache);
+
+
+
+

ostree_repo_devino_cache_get_type ()

+
GType
+ostree_repo_devino_cache_get_type (void);
+
+
+
+

ostree_repo_write_directory_to_mtree ()

+
gboolean
+ostree_repo_write_directory_to_mtree (OstreeRepo *self,
+                                      GFile *dir,
+                                      OstreeMutableTree *mtree,
+                                      OstreeRepoCommitModifier *modifier,
+                                      GCancellable *cancellable,
+                                      GError **error);
+

Store objects for dir + and all children into the repository self +, +overlaying the resulting filesystem hierarchy into mtree +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

dir

Path to a directory

 

mtree

Overlay directory contents into this tree

 

modifier

Optional modifier.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_dfd_to_mtree ()

+
gboolean
+ostree_repo_write_dfd_to_mtree (OstreeRepo *self,
+                                int dfd,
+                                const char *path,
+                                OstreeMutableTree *mtree,
+                                OstreeRepoCommitModifier *modifier,
+                                GCancellable *cancellable,
+                                GError **error);
+

Store as objects all contents of the directory referred to by dfd + +and path + all children into the repository self +, overlaying the +resulting filesystem hierarchy into mtree +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

dfd

Directory file descriptor

 

path

Path

 

mtree

Overlay directory contents into this tree

 

modifier

Optional modifier.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_archive_to_mtree ()

+
gboolean
+ostree_repo_write_archive_to_mtree (OstreeRepo *self,
+                                    GFile *archive,
+                                    OstreeMutableTree *mtree,
+                                    OstreeRepoCommitModifier *modifier,
+                                    gboolean autocreate_parents,
+                                    GCancellable *cancellable,
+                                    GError **error);
+

Import an archive file archive + into the repository, and write its +file structure to mtree +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

archive

A path to an archive file

 

mtree

The OstreeMutableTree to write to

 

modifier

Optional commit modifier.

[allow-none]

autocreate_parents

Autocreate parent directories

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_archive_to_mtree_from_fd ()

+
gboolean
+ostree_repo_write_archive_to_mtree_from_fd
+                               (OstreeRepo *self,
+                                int fd,
+                                OstreeMutableTree *mtree,
+                                OstreeRepoCommitModifier *modifier,
+                                gboolean autocreate_parents,
+                                GCancellable *cancellable,
+                                GError **error);
+

Read an archive from fd + and import it into the repository, writing +its file structure to mtree +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

An OstreeRepo

 

fd

A file descriptor to read the archive from

 

mtree

The OstreeMutableTree to write to

 

modifier

Optional commit modifier.

[allow-none]

autocreate_parents

Autocreate parent directories

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_mtree ()

+
gboolean
+ostree_repo_write_mtree (OstreeRepo *self,
+                         OstreeMutableTree *mtree,
+                         GFile **out_file,
+                         GCancellable *cancellable,
+                         GError **error);
+

Write all metadata objects for mtree + to repo; the resulting +out_file + points to the OSTREE_OBJECT_TYPE_DIR_TREE object that +the mtree + represented.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

mtree

Mutable tree

 

out_file

An OstreeRepoFile representing mtree +'s root.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_commit ()

+
gboolean
+ostree_repo_write_commit (OstreeRepo *self,
+                          const char *parent,
+                          const char *subject,
+                          const char *body,
+                          GVariant *metadata,
+                          OstreeRepoFile *root,
+                          char **out_commit,
+                          GCancellable *cancellable,
+                          GError **error);
+

Write a commit metadata object, referencing root_contents_checksum + +and root_metadata_checksum +. +This uses the current time as the commit timestamp, but it can be +overridden with an explicit timestamp via the +standard +SOURCE_DATE_EPOCH environment flag.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

parent

ASCII SHA256 checksum for parent, or NULL for none.

[nullable]

subject

Subject.

[nullable]

body

Body.

[nullable]

metadata

GVariant of type a{sv}, or NULL for none.

[nullable]

root

The tree to point the commit to

 

out_commit

Resulting ASCII SHA256 checksum for +commit.

[out][optional]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_commit_with_time ()

+
gboolean
+ostree_repo_write_commit_with_time (OstreeRepo *self,
+                                    const char *parent,
+                                    const char *subject,
+                                    const char *body,
+                                    GVariant *metadata,
+                                    OstreeRepoFile *root,
+                                    guint64 time,
+                                    char **out_commit,
+                                    GCancellable *cancellable,
+                                    GError **error);
+

Write a commit metadata object, referencing root_contents_checksum + +and root_metadata_checksum +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

parent

ASCII SHA256 checksum for parent, or NULL for none.

[nullable]

subject

Subject.

[nullable]

body

Body.

[nullable]

metadata

GVariant of type a{sv}, or NULL for none.

[nullable]

root

The tree to point the commit to

 

time

The time to use to stamp the commit

 

out_commit

Resulting ASCII SHA256 checksum for +commit.

[out][optional]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_read_commit_detached_metadata ()

+
gboolean
+ostree_repo_read_commit_detached_metadata
+                               (OstreeRepo *self,
+                                const char *checksum,
+                                GVariant **out_metadata,
+                                GCancellable *cancellable,
+                                GError **error);
+

OSTree commits can have arbitrary metadata associated; this +function retrieves them. If none exists, out_metadata + will be set +to NULL.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

checksum

ASCII SHA256 commit checksum

 

out_metadata

Metadata associated with commit in with format +"a{sv}", or NULL if none exists.

[out][nullable][transfer full]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_write_commit_detached_metadata ()

+
gboolean
+ostree_repo_write_commit_detached_metadata
+                               (OstreeRepo *self,
+                                const char *checksum,
+                                GVariant *metadata,
+                                GCancellable *cancellable,
+                                GError **error);
+

Replace any existing metadata associated with commit referred to by +checksum + with metadata +. If metadata + is NULL, then existing +data will be deleted.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

checksum

ASCII SHA256 commit checksum

 

metadata

Metadata to associate with commit in with format "a{sv}", or NULL to +delete.

[nullable]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_commit_add_composefs_metadata ()

+
gboolean
+ostree_repo_commit_add_composefs_metadata
+                               (OstreeRepo *self,
+                                guint format_version,
+                                GVariantDict *dict,
+                                OstreeRepoFile *repo_root,
+                                GCancellable *cancellable,
+                                GError **error);
+

Compute the composefs digest for a filesystem tree +and insert it into metadata for a commit object. The composefs +digest covers the entire filesystem tree and can be verified by +the composefs mount tooling.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

format_version

Must be zero

 

dict

A GVariant builder of type a{sv}

 

repo_root

the target filesystem tree

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_checkout_at_options_set_devino ()

+
void
+ostree_repo_checkout_at_options_set_devino
+                               (OstreeRepoCheckoutAtOptions *opts,
+                                OstreeRepoDevInoCache *cache);
+

This function simply assigns cache + to the devino_to_csum_cache member of +opts +; it's only useful for introspection.

+

Note that cache does *not* have its refcount incremented - the lifetime of +cache + must be equal to or greater than that of opts +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

opts

Checkout options

 

cache

Devino cache.

[transfer none][nullable]
+
+

Since: 2017.13

+
+
+
+

ostree_repo_checkout_tree ()

+
gboolean
+ostree_repo_checkout_tree (OstreeRepo *self,
+                           OstreeRepoCheckoutMode mode,
+                           OstreeRepoCheckoutOverwriteMode overwrite_mode,
+                           GFile *destination,
+                           OstreeRepoFile *source,
+                           GFileInfo *source_info,
+                           GCancellable *cancellable,
+                           GError **error);
+

Check out source + into destination +, which must live on the +physical filesystem. source + may be any subdirectory of a given +commit. The mode + and overwrite_mode + allow control over how the +files are checked out.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

mode

Options controlling all files

 

overwrite_mode

Whether or not to overwrite files

 

destination

Place tree here

 

source

Source tree

 

source_info

Source info

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_checkout_tree_at ()

+
gboolean
+ostree_repo_checkout_tree_at (OstreeRepo *self,
+                              OstreeRepoCheckoutOptions *options,
+                              int destination_dfd,
+                              const char *destination_path,
+                              const char *commit,
+                              GCancellable *cancellable,
+                              GError **error);
+

ostree_repo_checkout_tree_at is deprecated and should not be used in newly-written code.

+

Similar to ostree_repo_checkout_tree(), but uses directory-relative +paths for the destination, uses a new OstreeRepoCheckoutAtOptions, +and takes a commit checksum and optional subpath pair, rather than +requiring use of GFile APIs for the caller.

+

Note in addition that unlike ostree_repo_checkout_tree(), the +default is not to use the repository-internal uncompressed objects +cache.

+

This function is deprecated. Use ostree_repo_checkout_at() instead.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

options

Options.

[allow-none]

destination_dfd

Directory FD for destination

 

destination_path

Directory for destination

 

commit

Checksum for commit

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_checkout_at ()

+
gboolean
+ostree_repo_checkout_at (OstreeRepo *self,
+                         OstreeRepoCheckoutAtOptions *options,
+                         int destination_dfd,
+                         const char *destination_path,
+                         const char *commit,
+                         GCancellable *cancellable,
+                         GError **error);
+

Similar to ostree_repo_checkout_tree(), but uses directory-relative +paths for the destination, uses a new OstreeRepoCheckoutAtOptions, +and takes a commit checksum and optional subpath pair, rather than +requiring use of GFile APIs for the caller.

+

It also replaces ostree_repo_checkout_at() which was not safe to +use with GObject introspection.

+

Note in addition that unlike ostree_repo_checkout_tree(), the +default is not to use the repository-internal uncompressed objects +cache.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

options

Options.

[allow-none]

destination_dfd

Directory FD for destination

 

destination_path

Directory for destination

 

commit

Checksum for commit

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2016.8

+
+
+
+

ostree_repo_checkout_gc ()

+
gboolean
+ostree_repo_checkout_gc (OstreeRepo *self,
+                         GCancellable *cancellable,
+                         GError **error);
+

Call this after finishing a succession of checkout operations; it +will delete any currently-unused uncompressed objects from the +cache.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Repo

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_read_commit ()

+
gboolean
+ostree_repo_read_commit (OstreeRepo *self,
+                         const char *ref,
+                         GFile **out_root,
+                         char **out_commit,
+                         GCancellable *cancellable,
+                         GError **error);
+

Load the content for rev + into out_root +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

ref

Ref or ASCII checksum

 

out_root

An OstreeRepoFile corresponding to the root.

[out][optional]

out_commit

The resolved commit checksum.

[out][optional]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_list_objects ()

+
gboolean
+ostree_repo_list_objects (OstreeRepo *self,
+                          OstreeRepoListObjectsFlags flags,
+                          GHashTable **out_objects,
+                          GCancellable *cancellable,
+                          GError **error);
+

This function synchronously enumerates all objects in the +repository, returning data in out_objects +. out_objects + +maps from keys returned by ostree_object_name_serialize() +to GVariant values of type OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

flags

Flags controlling enumeration

 

out_objects

Map of serialized object name to variant data.

[out][transfer container][element-type GVariant GVariant]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

TRUE on success, FALSE on error, and error +will be set

+
+
+
+
+

ostree_repo_list_commit_objects_starting_with ()

+
gboolean
+ostree_repo_list_commit_objects_starting_with
+                               (OstreeRepo *self,
+                                const char *start,
+                                GHashTable **out_commits,
+                                GCancellable *cancellable,
+                                GError **error);
+

This function synchronously enumerates all commit objects starting +with start +, returning data in out_commits +.

+

To list all commit objects, provide the empty string "" for start +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

start

List commits starting with this checksum (empty string for all)

 

out_commits

Map of serialized commit name to variant data.

[out][transfer container][element-type GVariant GVariant]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

TRUE on success, FALSE on error, and error +will be set

+
+
+
+
+

ostree_repo_list_static_delta_names ()

+
gboolean
+ostree_repo_list_static_delta_names (OstreeRepo *self,
+                                     GPtrArray **out_deltas,
+                                     GCancellable *cancellable,
+                                     GError **error);
+

This function synchronously enumerates all static deltas in the +repository, returning its result in out_deltas +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

out_deltas

String name of deltas +(checksum-checksum.delta).

[out][element-type utf8][transfer container]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_list_static_delta_indexes ()

+
gboolean
+ostree_repo_list_static_delta_indexes (OstreeRepo *self,
+                                       GPtrArray **out_indexes,
+                                       GCancellable *cancellable,
+                                       GError **error);
+

This function synchronously enumerates all static delta indexes in the +repository, returning its result in out_indexes +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

out_indexes

String name of delta indexes +(checksum).

[out][element-type utf8][transfer container]

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2020.8

+
+
+
+

ostree_repo_static_delta_reindex ()

+
gboolean
+ostree_repo_static_delta_reindex (OstreeRepo *repo,
+                                  OstreeStaticDeltaIndexFlags flags,
+                                  const char *opt_to_commit,
+                                  GCancellable *cancellable,
+                                  GError **error);
+

The delta index for a particular commit lists all the existing deltas that can be used +when downloading that commit. This operation regenerates these indexes, either for +a particular commit (if opt_to_commit + is non-NULL), or for all commits that +are reachable by an existing delta (if opt_to_commit + is NULL).

+

This is normally called automatically when the summary is updated in +ostree_repo_regenerate_summary().

+

Locking: shared

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

repo

Repo

 

flags

Flags affecting the indexing operation

 

opt_to_commit

ASCII SHA256 checksum of target commit, or NULL to index all targets

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2020.8

+
+
+
+

ostree_repo_static_delta_generate ()

+
gboolean
+ostree_repo_static_delta_generate (OstreeRepo *self,
+                                   OstreeStaticDeltaGenerateOpt opt,
+                                   const char *from,
+                                   const char *to,
+                                   GVariant *metadata,
+                                   GVariant *params,
+                                   GCancellable *cancellable,
+                                   GError **error);
+

Generate a lookaside "static delta" from from + (NULL means +from-empty) which can generate the objects in to +. This delta is +an optimization over fetching individual objects, and can be +conveniently stored and applied offline.

+

The params + argument should be an a{sv}. The following attributes +are known:

+
    +
  • min-fallback-size: u: Minimum uncompressed size in megabytes to use fallback, 0 to disable +fallbacks

  • +
  • max-chunk-size: u: Maximum size in megabytes of a delta part

  • +
  • max-bsdiff-size: u: Maximum size in megabytes to consider bsdiff compression +for input files

  • +
  • compression: y: Compression type: 0=none, x=lzma, g=gzip

  • +
  • bsdiff-enabled: b: Enable bsdiff compression. Default TRUE.

  • +
  • inline-parts: b: Put part data in header, to get a single file delta. Default FALSE.

  • +
  • verbose: b: Print diagnostic messages. Default FALSE.

  • +
  • endianness: b: Deltas use host byte order by default; this option allows choosing +(G_BIG_ENDIAN or G_LITTLE_ENDIAN)

  • +
  • filename: ^ay: Save delta superblock to this filename (bytestring), and parts in the same +directory. Default saves to repository.

  • +
  • sign-name: ^ay: Signature type to use (bytestring).

  • +
  • sign-key-ids: ^as: NULL-terminated array of keys used to sign delta superblock.

  • +
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

opt

High level optimization choice

 

from

ASCII SHA256 checksum of origin, or NULL.

[nullable]

to

ASCII SHA256 checksum of target

 

metadata

Optional metadata.

[nullable]

params

Parameters, see below.

[nullable]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_static_delta_execute_offline_with_signature ()

+
gboolean
+ostree_repo_static_delta_execute_offline_with_signature
+                               (OstreeRepo *self,
+                                GFile *dir_or_file,
+                                OstreeSign *sign,
+                                gboolean skip_validation,
+                                GCancellable *cancellable,
+                                GError **error);
+

Given a directory representing an already-downloaded static delta +on disk, apply it, generating a new commit. +If sign is passed, the static delta signature is verified. +If sign-verify-deltas configuration option is set and static delta is signed, +signature verification will be mandatory before apply the static delta. +The directory must be named with the form "FROM-TO", where both are +checksums, and it must contain a file named "superblock", along with at least +one part.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

dir_or_file

Path to a directory containing static delta data, or directly to the superblock

 

sign

Signature engine used to check superblock

 

skip_validation

If TRUE, assume data integrity

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2020.7

+
+
+
+

ostree_repo_static_delta_execute_offline ()

+
gboolean
+ostree_repo_static_delta_execute_offline
+                               (OstreeRepo *self,
+                                GFile *dir_or_file,
+                                gboolean skip_validation,
+                                GCancellable *cancellable,
+                                GError **error);
+

Given a directory representing an already-downloaded static delta +on disk, apply it, generating a new commit. The directory must be +named with the form "FROM-TO", where both are checksums, and it +must contain a file named "superblock", along with at least one part.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

dir_or_file

Path to a directory containing static delta data, or directly to the superblock

 

skip_validation

If TRUE, assume data integrity

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_static_delta_verify_signature ()

+
gboolean
+ostree_repo_static_delta_verify_signature
+                               (OstreeRepo *self,
+                                const char *delta_id,
+                                OstreeSign *sign,
+                                char **out_success_message,
+                                GError **error);
+

Verify static delta file signature.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

delta_id

delta path

 

sign

Signature engine used to check superblock

 

out_success_message

success message.

[out][nullable][optional]

error

Error

 
+
+
+

Returns

+

TRUE if the signature of static delta file is valid using the +signature engine provided, FALSE otherwise.

+
+

Since: 2020.7

+
+
+
+

ostree_repo_traverse_new_reachable ()

+
GHashTable *
+ostree_repo_traverse_new_reachable (void);
+

This hash table is a set of GVariant which can be accessed via +ostree_object_name_deserialize().

+
+

Returns

+

A new hash table.

+

[transfer container][element-type GVariant GVariant]

+
+
+
+
+

ostree_repo_traverse_new_parents ()

+
GHashTable *
+ostree_repo_traverse_new_parents (void);
+

This hash table is a mapping from GVariant which can be accessed +via ostree_object_name_deserialize() to a GVariant containing either +a similar GVariant or and array of them, listing the parents of the key.

+
+

Returns

+

A new hash table.

+

[transfer container][element-type GVariant GVariant]

+
+

Since: 2018.5

+
+
+
+

ostree_repo_traverse_parents_get_commits ()

+
char **
+ostree_repo_traverse_parents_get_commits
+                               (GHashTable *parents,
+                                GVariant *object);
+

Gets all the commits that a certain object belongs to, as recorded +by a parents table gotten from ostree_repo_traverse_commit_union_with_parents.

+
+

Returns

+

An array of checksums for +the commits the key belongs to.

+

[transfer full][array zero-terminated=1]

+
+

Since: 2018.5

+
+
+
+

ostree_repo_traverse_commit ()

+
gboolean
+ostree_repo_traverse_commit (OstreeRepo *repo,
+                             const char *commit_checksum,
+                             int maxdepth,
+                             GHashTable **out_reachable,
+                             GCancellable *cancellable,
+                             GError **error);
+

Create a new set out_reachable + containing all objects reachable +from commit_checksum +, traversing maxdepth + parent commits.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

repo

Repo

 

commit_checksum

ASCII SHA256 checksum

 

maxdepth

Traverse this many parent commits, -1 for unlimited

 

out_reachable

Set of reachable +objects.

[out][transfer container][element-type GVariant GVariant]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_traverse_commit_union ()

+
gboolean
+ostree_repo_traverse_commit_union (OstreeRepo *repo,
+                                   const char *commit_checksum,
+                                   int maxdepth,
+                                   GHashTable *inout_reachable,
+                                   GCancellable *cancellable,
+                                   GError **error);
+

Update the set inout_reachable + containing all objects reachable +from commit_checksum +, traversing maxdepth + parent commits.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

repo

Repo

 

commit_checksum

ASCII SHA256 checksum

 

maxdepth

Traverse this many parent commits, -1 for unlimited

 

inout_reachable

Set of reachable objects

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_traverse_commit_union_with_parents ()

+
gboolean
+ostree_repo_traverse_commit_union_with_parents
+                               (OstreeRepo *repo,
+                                const char *commit_checksum,
+                                int maxdepth,
+                                GHashTable *inout_reachable,
+                                GHashTable *inout_parents,
+                                GCancellable *cancellable,
+                                GError **error);
+

Update the set inout_reachable + containing all objects reachable +from commit_checksum +, traversing maxdepth + parent commits.

+

Additionally this constructs a mapping from each object to the parents +of the object, which can be used to track which commits an object +belongs to.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

repo

Repo

 

commit_checksum

ASCII SHA256 checksum

 

maxdepth

Traverse this many parent commits, -1 for unlimited

 

inout_reachable

Set of reachable objects

 

inout_parents

Map from object to parent object

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2018.5

+
+
+
+

ostree_repo_traverse_commit_with_flags ()

+
gboolean
+ostree_repo_traverse_commit_with_flags
+                               (OstreeRepo *repo,
+                                OstreeRepoCommitTraverseFlags flags,
+                                const char *commit_checksum,
+                                int maxdepth,
+                                GHashTable *inout_reachable,
+                                GHashTable *inout_parents,
+                                GCancellable *cancellable,
+                                GError **error);
+

Update the set inout_reachable + containing all objects reachable +from commit_checksum +, traversing maxdepth + parent commits.

+

Additionally this constructs a mapping from each object to the parents +of the object, which can be used to track which commits an object +belongs to.

+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

repo

Repo

 

flags

change traversal behaviour according to these flags

 

commit_checksum

ASCII SHA256 checksum

 

maxdepth

Traverse this many parent commits, -1 for unlimited

 

inout_reachable

Set of reachable objects

 

inout_parents

Map from object to parent object

 

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2018.5

+
+
+
+

ostree_repo_commit_traverse_iter_cleanup ()

+
void
+ostree_repo_commit_traverse_iter_cleanup
+                               (void *p);
+
+
+
+

ostree_repo_commit_traverse_iter_clear ()

+
void
+ostree_repo_commit_traverse_iter_clear
+                               (OstreeRepoCommitTraverseIter *iter);
+
+
+
+

ostree_repo_commit_traverse_iter_get_dir ()

+
void
+ostree_repo_commit_traverse_iter_get_dir
+                               (OstreeRepoCommitTraverseIter *iter,
+                                char **out_name,
+                                char **out_content_checksum,
+                                char **out_meta_checksum);
+

Return information on the current directory. This function may +only be called if OSTREE_REPO_COMMIT_ITER_RESULT_DIR was returned +from ostree_repo_commit_traverse_iter_next().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

iter

An iter

 

out_name

Name of current dir.

[out][transfer none]

out_content_checksum

Checksum of current content.

[out][transfer none]

out_meta_checksum

Checksum of current metadata.

[out][transfer none]
+
+
+
+
+

ostree_repo_commit_traverse_iter_get_file ()

+
void
+ostree_repo_commit_traverse_iter_get_file
+                               (OstreeRepoCommitTraverseIter *iter,
+                                char **out_name,
+                                char **out_checksum);
+

Return information on the current file. This function may only be +called if OSTREE_REPO_COMMIT_ITER_RESULT_FILE was returned from +ostree_repo_commit_traverse_iter_next().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

iter

An iter

 

out_name

Name of current file.

[out][transfer none]

out_checksum

Checksum of current file.

[out][transfer none]
+
+
+
+
+

ostree_repo_commit_traverse_iter_init_commit ()

+
gboolean
+ostree_repo_commit_traverse_iter_init_commit
+                               (OstreeRepoCommitTraverseIter *iter,
+                                OstreeRepo *repo,
+                                GVariant *commit,
+                                OstreeRepoCommitTraverseFlags flags,
+                                GError **error);
+

Initialize (in place) an iterator over the root of a commit object.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

iter

An iter

 

repo

A repo

 

commit

Variant of type OSTREE_OBJECT_TYPE_COMMIT

 

flags

Flags

 

error

Error

 
+
+
+
+
+

ostree_repo_commit_traverse_iter_init_dirtree ()

+
gboolean
+ostree_repo_commit_traverse_iter_init_dirtree
+                               (OstreeRepoCommitTraverseIter *iter,
+                                OstreeRepo *repo,
+                                GVariant *dirtree,
+                                OstreeRepoCommitTraverseFlags flags,
+                                GError **error);
+

Initialize (in place) an iterator over a directory tree.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

iter

An iter

 

repo

A repo

 

dirtree

Variant of type OSTREE_OBJECT_TYPE_DIR_TREE

 

flags

Flags

 

error

Error

 
+
+
+
+
+

ostree_repo_commit_traverse_iter_next ()

+
OstreeRepoCommitIterResult
+ostree_repo_commit_traverse_iter_next (OstreeRepoCommitTraverseIter *iter,
+                                       GCancellable *cancellable,
+                                       GError **error);
+

Step the interator to the next item. Files will be returned first, +then subdirectories. Call this in a loop; upon encountering +OSTREE_REPO_COMMIT_ITER_RESULT_END, there will be no more files or +directories. If OSTREE_REPO_COMMIT_ITER_RESULT_DIR is returned, +then call ostree_repo_commit_traverse_iter_get_dir() to retrieve +data for that directory. Similarly, if +OSTREE_REPO_COMMIT_ITER_RESULT_FILE is returned, call +ostree_repo_commit_traverse_iter_get_file().

+

If OSTREE_REPO_COMMIT_ITER_RESULT_ERROR is returned, it is a +program error to call any further API on iter + except for +ostree_repo_commit_traverse_iter_clear().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

iter

An iter

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_prune ()

+
gboolean
+ostree_repo_prune (OstreeRepo *self,
+                   OstreeRepoPruneFlags flags,
+                   gint depth,
+                   gint *out_objects_total,
+                   gint *out_objects_pruned,
+                   guint64 *out_pruned_object_size_total,
+                   GCancellable *cancellable,
+                   GError **error);
+

Delete content from the repository. By default, this function will +only delete "orphaned" objects not referred to by any commit. This +can happen during a local commit operation, when we have written +content objects but not saved the commit referencing them.

+

However, if OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY is provided, instead +of traversing all commits, only refs will be used. Particularly +when combined with depth +, this is a convenient way to delete +history from the repository.

+

Use the OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE to just determine +statistics on objects that would be deleted, without actually +deleting them.

+

Locking: exclusive

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

flags

Options controlling prune process

 

depth

Stop traversal after this many iterations (-1 for unlimited)

 

out_objects_total

Number of objects found.

[out]

out_objects_pruned

Number of objects deleted.

[out]

out_pruned_object_size_total

Storage size in bytes of objects deleted.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_prune_static_deltas ()

+
gboolean
+ostree_repo_prune_static_deltas (OstreeRepo *self,
+                                 const char *commit,
+                                 GCancellable *cancellable,
+                                 GError **error);
+

Prune static deltas, if COMMIT is specified then delete static delta files only +targeting that commit; otherwise any static delta of non existing commits are +deleted.

+

Locking: exclusive

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

commit

ASCII SHA256 checksum for commit, or NULL for each +non existing commit.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_traverse_reachable_refs ()

+
gboolean
+ostree_repo_traverse_reachable_refs (OstreeRepo *self,
+                                     guint depth,
+                                     GHashTable *reachable,
+                                     GCancellable *cancellable,
+                                     GError **error);
+

Add all commit objects directly reachable via a ref to reachable +.

+

Locking: shared

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

depth

Depth of traversal

 

reachable

Set of reachable objects (will be modified).

[element-type GVariant GVariant]

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2018.6

+
+
+
+

ostree_repo_prune_from_reachable ()

+
gboolean
+ostree_repo_prune_from_reachable (OstreeRepo *self,
+                                  OstreeRepoPruneOptions *options,
+                                  gint *out_objects_total,
+                                  gint *out_objects_pruned,
+                                  guint64 *out_pruned_object_size_total,
+                                  GCancellable *cancellable,
+                                  GError **error);
+

Delete content from the repository. This function is the "backend" +half of the higher level ostree_repo_prune(). To use this function, +you determine the root set yourself, and this function finds all other +unreferenced objects and deletes them.

+

Use this API when you want to perform more selective pruning - for example, +retain all commits from a production branch, but just GC some history from +your dev branch.

+

The OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE flag may be specified to just determine +statistics on objects that would be deleted, without actually deleting them.

+

Locking: exclusive

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

options

Options controlling prune process

 

out_objects_total

Number of objects found.

[out]

out_objects_pruned

Number of objects deleted.

[out]

out_pruned_object_size_total

Storage size in bytes of objects deleted.

[out]

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2017.1

+
+
+
+

ostree_repo_pull ()

+
gboolean
+ostree_repo_pull (OstreeRepo *self,
+                  const char *remote_name,
+                  char **refs_to_fetch,
+                  OstreeRepoPullFlags flags,
+                  OstreeAsyncProgress *progress,
+                  GCancellable *cancellable,
+                  GError **error);
+

Connect to the remote repository, fetching the specified set of +refs refs_to_fetch +. For each ref that is changed, download the +commit, all metadata, and all content objects, storing them safely +on disk in self +.

+

If flags + contains OSTREE_REPO_PULL_FLAGS_MIRROR, and +the refs_to_fetch + is NULL, and the remote repository contains a +summary file, then all refs will be fetched.

+

If flags + contains OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY, then only the +metadata for the commits in refs_to_fetch + is pulled.

+

Warning: This API will iterate the thread default main context, +which is a bug, but kept for compatibility reasons. If you want to +avoid this, use g_main_context_push_thread_default() to push a new +one around this call.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

remote_name

Name of remote

 

refs_to_fetch

Optional list of +refs; if NULL, fetch all configured refs.

[array zero-terminated=1][element-type utf8][allow-none]

flags

Options controlling fetch behavior

 

progress

Progress.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_pull_one_dir ()

+
gboolean
+ostree_repo_pull_one_dir (OstreeRepo *self,
+                          const char *remote_name,
+                          const char *dir_to_pull,
+                          char **refs_to_fetch,
+                          OstreeRepoPullFlags flags,
+                          OstreeAsyncProgress *progress,
+                          GCancellable *cancellable,
+                          GError **error);
+

This is similar to ostree_repo_pull(), but only fetches a single +subpath.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

remote_name

Name of remote

 

dir_to_pull

Subdirectory path

 

refs_to_fetch

Optional list of +refs; if NULL, fetch all configured refs.

[array zero-terminated=1][element-type utf8][allow-none]

flags

Options controlling fetch behavior

 

progress

Progress.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_pull_with_options ()

+
gboolean
+ostree_repo_pull_with_options (OstreeRepo *self,
+                               const char *remote_name_or_baseurl,
+                               GVariant *options,
+                               OstreeAsyncProgress *progress,
+                               GCancellable *cancellable,
+                               GError **error);
+

Like ostree_repo_pull(), but supports an extensible set of flags. +The following are currently defined:

+
    +
  • refs (as): Array of string refs

  • +
  • collection-refs (a(sss)): Array of (collection ID, ref name, checksum) tuples to pull; +mutually exclusive with refs and override-commit-ids. Checksums may be the empty +string to pull the latest commit for that ref

  • +
  • flags (i): An instance of OstreeRepoPullFlags

  • +
  • subdir (s): Pull just this subdirectory

  • +
  • subdirs (as): Pull just these subdirectories

  • +
  • override-remote-name (s): If local, add this remote to refspec

  • +
  • gpg-verify (b): GPG verify commits

  • +
  • gpg-verify-summary (b): GPG verify summary

  • +
  • disable-sign-verify (b): Disable signapi verification of commits

  • +
  • disable-sign-verify-summary (b): Disable signapi verification of the summary

  • +
  • depth (i): How far in the history to traverse; default is 0, -1 means infinite

  • +
  • per-object-fsync (b): Perform disk writes more slowly, avoiding a single large I/O sync

  • +
  • disable-static-deltas (b): Do not use static deltas

  • +
  • require-static-deltas (b): Require static deltas

  • +
  • override-commit-ids (as): Array of specific commit IDs to fetch for refs

  • +
  • timestamp-check (b): Verify commit timestamps are newer than current (when pulling via +ref); Since: 2017.11

  • +
  • timestamp-check-from-rev (s): Verify that all fetched commit timestamps are newer than +timestamp of given rev; Since: 2020.4

  • +
  • max-metadata-size (t): Restrict metadata objects to a maximum number of bytes; 0 to +disable. Since: 2018.9

  • +
  • dry-run (b): Only print information on what will be downloaded (requires static deltas)

  • +
  • override-url (s): Fetch objects from this URL if remote specifies no metalink in options

  • +
  • inherit-transaction (b): Don't initiate, finish or abort a transaction, useful to do +multiple pulls in one transaction.

  • +
  • http-headers (a(ss)): Additional headers to add to all HTTP requests

  • +
  • update-frequency (u): Frequency to call the async progress callback in milliseconds, if +any; only values higher than 0 are valid

  • +
  • localcache-repos (as): File paths for local repos to use as caches when doing remote +fetches

  • +
  • append-user-agent (s): Additional string to append to the user agent

  • +
  • n-network-retries (u): Number of times to retry each download on receiving +a transient network error, such as a socket timeout; default is 5, 0 +means return errors without retrying. Since: 2018.6

  • +
  • low-speed-limit-bytes (u): The average transfer speed per second of a transfer + during the time set via "low-speed-time-seconds" for libcurl to abort.

  • +
  • low-speed-time-seconds (u): The time in number seconds that the transfer + speed should be below the "low-speed-limit-bytes" setting for libcurl to abort.

  • +
  • retry-all-network-errors (b): Retry when network issues happen, instead of + failing automatically. Currently only affects libcurl. (Default set to true)

  • +
  • max-outstanding-fetcher-requests (u): The max amount of concurrent connections allowed.

  • +
  • ref-keyring-map (a(sss)): Array of (collection ID, ref name, keyring +remote name) tuples specifying which remote's keyring should be used when +doing GPG verification of each collection-ref. This is useful to prevent a +remote from serving malicious updates to refs which did not originate from +it. This can be a subset or superset of the refs being pulled; any ref +not being pulled will be ignored and any ref without a keyring remote +will be verified with the keyring of the remote being pulled from.

  • +
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

remote_name_or_baseurl

Name of remote or file:// url

 

options

A GVariant a{sv} with an extensible set of flags.

 

progress

Progress.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2020.9

+
+
+
+

ostree_repo_pull_default_console_progress_changed ()

+
void
+ostree_repo_pull_default_console_progress_changed
+                               (OstreeAsyncProgress *progress,
+                                gpointer user_data);
+

Convenient "changed" callback for use with +ostree_async_progress_new_and_connect() when pulling from a remote +repository.

+

Depending on the state of the OstreeAsyncProgress, either displays a +custom status message, or else outstanding fetch progress in bytes/sec, +or else outstanding content or metadata writes to the repository in +number of objects.

+

Compatibility note: this function previously assumed that user_data + +was a pointer to a GSConsole instance. This is no longer the case, +and user_data + is ignored.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

progress

Async progress

 

user_data

User data.

[allow-none]
+
+
+
+
+

ostree_repo_sign_commit ()

+
gboolean
+ostree_repo_sign_commit (OstreeRepo *self,
+                         const gchar *commit_checksum,
+                         const gchar *key_id,
+                         const gchar *homedir,
+                         GCancellable *cancellable,
+                         GError **error);
+

Add a GPG signature to a commit.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

commit_checksum

SHA256 of given commit to sign

 

key_id

Use this GPG key id

 

homedir

GPG home directory, or NULL.

[allow-none]

cancellable

A GCancellable

 

error

a GError

 
+
+
+
+
+

ostree_repo_append_gpg_signature ()

+
gboolean
+ostree_repo_append_gpg_signature (OstreeRepo *self,
+                                  const gchar *commit_checksum,
+                                  GBytes *signature_bytes,
+                                  GCancellable *cancellable,
+                                  GError **error);
+

Append a GPG signature to a commit.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

commit_checksum

SHA256 of given commit to sign

 

signature_bytes

Signature data

 

cancellable

A GCancellable

 

error

a GError

 
+
+
+
+
+

ostree_repo_add_gpg_signature_summary ()

+
gboolean
+ostree_repo_add_gpg_signature_summary (OstreeRepo *self,
+                                       const gchar **key_id,
+                                       const gchar *homedir,
+                                       GCancellable *cancellable,
+                                       GError **error);
+

Add a GPG signature to a summary file.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

key_id

NULL-terminated array of GPG keys.

[array zero-terminated=1][element-type utf8]

homedir

GPG home directory, or NULL.

[allow-none]

cancellable

A GCancellable

 

error

a GError

 
+
+
+
+
+

ostree_repo_gpg_sign_data ()

+
gboolean
+ostree_repo_gpg_sign_data (OstreeRepo *self,
+                           GBytes *data,
+                           GBytes *old_signatures,
+                           const gchar **key_id,
+                           const gchar *homedir,
+                           GBytes **out_signatures,
+                           GCancellable *cancellable,
+                           GError **error);
+

Sign the given data + with the specified keys in key_id +. Similar to +ostree_repo_add_gpg_signature_summary() but can be used on any +data.

+

You can use ostree_repo_gpg_verify_data() to verify the signatures.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

data

Data as a GBytes

 

old_signatures

Existing signatures to append to (or NULL).

[nullable]

key_id

NULL-terminated array of GPG keys.

[array zero-terminated=1][element-type utf8]

homedir

GPG home directory, or NULL.

[nullable]

out_signatures

in case of success will contain signature.

[out]

cancellable

A GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE if data +has been signed successfully, +FALSE in case of error (error +will contain the reason).

+
+

Since: 2020.8

+
+
+
+

ostree_repo_gpg_verify_data ()

+
OstreeGpgVerifyResult *
+ostree_repo_gpg_verify_data (OstreeRepo *self,
+                             const gchar *remote_name,
+                             GBytes *data,
+                             GBytes *signatures,
+                             GFile *keyringdir,
+                             GFile *extra_keyring,
+                             GCancellable *cancellable,
+                             GError **error);
+

Verify signatures + for data + using GPG keys in the keyring for +remote_name +, and return an OstreeGpgVerifyResult.

+

The remote_name + parameter can be NULL. In that case it will do +the verifications using GPG keys in the keyrings of all remotes.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repository

 

remote_name

Name of remote.

[nullable]

data

Data as a GBytes

 

signatures

Signatures as a GBytes

 

keyringdir

Path to directory GPG keyrings; overrides built-in default if given.

[nullable]

extra_keyring

Path to additional keyring file (not a directory).

[nullable]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

an OstreeGpgVerifyResult, or NULL on error.

+

[transfer full]

+
+

Since: 2016.6

+
+
+
+

ostree_repo_signature_verify_commit_data ()

+
gboolean
+ostree_repo_signature_verify_commit_data
+                               (OstreeRepo *self,
+                                const char *remote_name,
+                                GBytes *commit_data,
+                                GBytes *commit_metadata,
+                                OstreeRepoVerifyFlags flags,
+                                char **out_results,
+                                GError **error);
+

Validate the commit data using the commit metadata which must +contain at least one valid signature. If GPG and signapi are +both enabled, then both must find at least one valid signature.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

remote_name

Name of remote

 

commit_data

Commit object data (GVariant)

 

commit_metadata

Commit metadata (GVariant a{sv}), must contain at least one valid signature

 

flags

Optionally disable GPG or signapi

 

out_results

Textual description of results.

[optional][out][transfer full]

error

Error

 
+
+
+
+
+

ostree_repo_verify_commit ()

+
gboolean
+ostree_repo_verify_commit (OstreeRepo *self,
+                           const gchar *commit_checksum,
+                           GFile *keyringdir,
+                           GFile *extra_keyring,
+                           GCancellable *cancellable,
+                           GError **error);
+

Check for a valid GPG signature on commit named by the ASCII +checksum commit_checksum +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repository

 

commit_checksum

ASCII SHA256 checksum

 

keyringdir

Path to directory GPG keyrings; overrides built-in default if given.

[allow-none]

extra_keyring

Path to additional keyring file (not a directory).

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

TRUE if there was a GPG signature from a trusted keyring, otherwise FALSE

+
+
+
+
+

ostree_repo_verify_commit_ext ()

+
OstreeGpgVerifyResult *
+ostree_repo_verify_commit_ext (OstreeRepo *self,
+                               const gchar *commit_checksum,
+                               GFile *keyringdir,
+                               GFile *extra_keyring,
+                               GCancellable *cancellable,
+                               GError **error);
+

Read GPG signature(s) on the commit named by the ASCII checksum +commit_checksum + and return detailed results.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repository

 

commit_checksum

ASCII SHA256 checksum

 

keyringdir

Path to directory GPG keyrings; overrides built-in default if given.

[allow-none]

extra_keyring

Path to additional keyring file (not a directory).

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

an OstreeGpgVerifyResult, or NULL on error.

+

[transfer full]

+
+
+
+
+

ostree_repo_verify_commit_for_remote ()

+
OstreeGpgVerifyResult *
+ostree_repo_verify_commit_for_remote (OstreeRepo *self,
+                                      const gchar *commit_checksum,
+                                      const gchar *remote_name,
+                                      GCancellable *cancellable,
+                                      GError **error);
+

Read GPG signature(s) on the commit named by the ASCII checksum +commit_checksum + and return detailed results, based on the keyring +configured for remote +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repository

 

commit_checksum

ASCII SHA256 checksum

 

remote_name

OSTree remote to use for configuration

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

an OstreeGpgVerifyResult, or NULL on error.

+

[transfer full]

+
+

Since: 2016.14

+
+
+
+

ostree_repo_verify_summary ()

+
OstreeGpgVerifyResult *
+ostree_repo_verify_summary (OstreeRepo *self,
+                            const char *remote_name,
+                            GBytes *summary,
+                            GBytes *signatures,
+                            GCancellable *cancellable,
+                            GError **error);
+

Verify signatures + for summary + data using GPG keys in the keyring for +remote_name +, and return an OstreeGpgVerifyResult.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

remote_name

Name of remote

 

summary

Summary data as a GBytes

 

signatures

Summary signatures as a GBytes

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

an OstreeGpgVerifyResult, or NULL on error.

+

[transfer full]

+
+
+
+
+

ostree_repo_regenerate_metadata ()

+
gboolean
+ostree_repo_regenerate_metadata (OstreeRepo *self,
+                                 GVariant *additional_metadata,
+                                 GVariant *options,
+                                 GCancellable *cancellable,
+                                 GError **error);
+

Regenerate the OSTree repository metadata used by clients to describe +available branches and other metadata.

+

The repository metadata currently consists of the summary file. See +ostree_repo_regenerate_summary() and OSTREE_SUMMARY_GVARIANT_FORMAT for +additional details on its contents.

+

Additionally, if the core/collection-id key is set in the configuration, a +OSTREE_REPO_METADATA_REF commit will be created.

+

The following options + are currently defined:

+
    +
  • gpg-key-ids (as): Array of GPG key IDs to sign the metadata with.

  • +
  • gpg-homedir (s): GPG home directory.

  • +
  • sign-keys (av): Array of keys to sign the metadata with. The key +type is specific to the sign engine used.

  • +
  • sign-type (s): Sign engine type to use. If not specified, +OSTREE_SIGN_NAME_ED25519 is used.

  • +
+

Locking: shared

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

additional_metadata

A GVariant a{sv}, or NULL.

[nullable]

options

A GVariant a{sv} with an extensible set of flags.

[nullable]

cancellable

Cancellable

 

error

Error

 
+
+

Since: 2023.1

+
+
+
+

ostree_repo_regenerate_summary ()

+
gboolean
+ostree_repo_regenerate_summary (OstreeRepo *self,
+                                GVariant *additional_metadata,
+                                GCancellable *cancellable,
+                                GError **error);
+

An OSTree repository can contain a high level "summary" file that +describes the available branches and other metadata.

+

If the timetable for making commits and updating the summary file is fairly +regular, setting the ostree.summary.expires key in additional_metadata + +will aid clients in working out when to check for updates.

+

It is regenerated automatically after any ref is +added, removed, or updated if core/auto-update-summary is set.

+

If the core/collection-id key is set in the configuration, it will be +included as OSTREE_SUMMARY_COLLECTION_ID in the summary file. Refs that +have associated collection IDs will be included in the generated summary +file, listed under the OSTREE_SUMMARY_COLLECTION_MAP key. Collection IDs +and refs in OSTREE_SUMMARY_COLLECTION_MAP are guaranteed to be in +lexicographic order.

+

Locking: shared (Prior to 2021.7, this was exclusive)

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Repo

 

additional_metadata

A GVariant of type a{sv}, or NULL.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

Types and Values

+
+

OstreeRepo

+
typedef struct OstreeRepo OstreeRepo;
+
+

Private instance structure.

+
+
+
+

enum OstreeRepoMode

+

See the documentation of OstreeRepo for more information about the +possible modes.

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_MODE_BARE

+

Files are stored as themselves; checkouts are hardlinks; can only be +written as root

+
 

OSTREE_REPO_MODE_ARCHIVE

+

Files are compressed, should be owned by non-root. Can be served via +HTTP. Since: 2017.12

+
 

OSTREE_REPO_MODE_ARCHIVE_Z2

+

Legacy alias for OSTREE_REPO_MODE_ARCHIVE

+
 

OSTREE_REPO_MODE_BARE_USER

+

Files are stored as themselves, except ownership; can be written by +user. Hardlinks work only in user checkouts.

+
 

OSTREE_REPO_MODE_BARE_USER_ONLY

+

Same as BARE_USER, but all metadata is not stored, so it can +only be used for user checkouts. Does not need xattrs.

+
 

OSTREE_REPO_MODE_BARE_SPLIT_XATTRS

+

Same as BARE_USER, but xattrs are stored separately from +file content, with dedicated object types.

+
 
+
+
+
+
+

enum OstreeRepoLockType

+

Flags controlling repository locking.

+
+

Members

+
+++++ + + + + + + + + + + + + +

OSTREE_REPO_LOCK_SHARED

+

A "read only" lock; multiple readers are allowed.

+
 

OSTREE_REPO_LOCK_EXCLUSIVE

+

A writable lock at most one writer can be active, and zero readers.

+
 
+
+

Since: 2021.3

+
+
+
+

OstreeRepoAutoLock

+
typedef struct OstreeRepoAutoLock OstreeRepoAutoLock;
+
+

An opaque type for use with ostree_repo_auto_lock_push().

+

Since: 2021.3

+
+
+
+

enum OstreeRepoRemoteChange

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_REMOTE_CHANGE_ADD

+

Add a remote

+
 

OSTREE_REPO_REMOTE_CHANGE_ADD_IF_NOT_EXISTS

+

Like above, but do nothing if the remote exists

+
 

OSTREE_REPO_REMOTE_CHANGE_DELETE

+

Delete a remote

+
 

OSTREE_REPO_REMOTE_CHANGE_DELETE_IF_EXISTS

+

Delete a remote, do nothing if the remote does not +exist

+
 

OSTREE_REPO_REMOTE_CHANGE_REPLACE

+

Add or replace a remote (Since: 2019.2)

+
 
+
+
+
+
+

struct OstreeRepoTransactionStats

+
struct OstreeRepoTransactionStats {
+  guint metadata_objects_total;
+  guint metadata_objects_written;
+  guint content_objects_total;
+  guint content_objects_written;
+  guint64 content_bytes_written;
+  guint devino_cache_hits;
+
+  guint padding1;
+  guint64 padding2;
+  guint64 padding3;
+  guint64 padding4;
+};
+
+

A list of statistics for each transaction that may be +interesting for reporting purposes.

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

guint metadata_objects_total;

The total number of metadata objects +in the repository after this transaction has completed.

 

guint metadata_objects_written;

The number of metadata objects that +were written to the repository in this transaction.

 

guint content_objects_total;

The total number of content objects +in the repository after this transaction has completed.

 

guint content_objects_written;

The number of content objects that +were written to the repository in this transaction.

 

guint64 content_bytes_written;

The amount of data added to the repository, +in bytes, counting only content objects.

 

guint devino_cache_hits;

  

guint padding1;

reserved

 

guint64 padding2;

reserved

 

guint64 padding3;

reserved

 

guint64 padding4;

reserved

 
+
+
+
+
+

enum OstreeRepoResolveRevExtFlags

+
+

Members

+
+++++ + + + + + + + + + + + + +

OSTREE_REPO_RESOLVE_REV_EXT_NONE

+

No flags.

+
 

OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY

+

Exclude remote and mirrored refs. Since: 2019.2

+
 
+
+
+
+
+

enum OstreeRepoListRefsExtFlags

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_LIST_REFS_EXT_NONE

+

No flags.

+
 

OSTREE_REPO_LIST_REFS_EXT_ALIASES

+

Only list aliases. Since: 2017.10

+
 

OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES

+

Exclude remote refs. Since: 2017.11

+
 

OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS

+

Exclude mirrored refs. Since: 2019.2

+
 
+
+
+
+
+

enum OstreeRepoCommitState

+

Flags representing the state of a commit in the local repository, as returned +by ostree_repo_load_commit().

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + +

OSTREE_REPO_COMMIT_STATE_NORMAL

+

Commit is complete. This is the default. +(Since: 2017.14.)

+
 

OSTREE_REPO_COMMIT_STATE_PARTIAL

+

One or more objects are missing from the +local copy of the commit, but metadata is present. (Since: 2015.7.)

+
 

OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL

+

One or more objects are missing from the +local copy of the commit, due to an fsck --delete. (Since: 2019.4.)

+
 
+
+

Since: 2015.7

+
+
+
+

enum OstreeRepoCommitFilterResult

+
+

Members

+
+++++ + + + + + + + + + + + + +

OSTREE_REPO_COMMIT_FILTER_ALLOW

+

Do commit this object

+
 

OSTREE_REPO_COMMIT_FILTER_SKIP

+

Ignore this object

+
 
+
+
+
+
+

OstreeRepoCommitModifier

+
typedef struct OstreeRepoCommitModifier OstreeRepoCommitModifier;
+
+

A structure allowing control over commits.

+
+
+
+

enum OstreeRepoCommitModifierFlags

+

Flags modifying commit behavior. In bare-user-only mode, +OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS + and +OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS + are automatically enabled.

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_COMMIT_MODIFIER_FLAGS_NONE

+

No special flags

+
 

OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS

+

Do not process extended attributes

+
 

OSTREE_REPO_COMMIT_MODIFIER_FLAGS_GENERATE_SIZES

+

Generate size information.

+
 

OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS

+

Canonicalize permissions.

+
 

OSTREE_REPO_COMMIT_MODIFIER_FLAGS_ERROR_ON_UNLABELED

+

Emit an error if configured SELinux +policy does not provide a label

+
 

OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CONSUME

+

Delete added files/directories after commit; Since: +2017.13

+
 

OSTREE_REPO_COMMIT_MODIFIER_FLAGS_DEVINO_CANONICAL

+

If a devino cache hit is found, skip +modifier filters (non-directories only); Since: 2017.14

+
 

OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SELINUX_LABEL_V1

+

For SELinux and other systems, label +/usr/etc as if it was /etc.

+
 
+
+
+
+
+

enum OstreeRepoCheckoutMode

+
+

Members

+
+++++ + + + + + + + + + + + + +

OSTREE_REPO_CHECKOUT_MODE_NONE

+

No special options

+
 

OSTREE_REPO_CHECKOUT_MODE_USER

+

Ignore uid/gid of files

+
 
+
+
+
+
+

enum OstreeRepoCheckoutOverwriteMode

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_CHECKOUT_OVERWRITE_NONE

+

No special options

+
 

OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES

+

When layering checkouts, unlink() and replace +existing files, but do not modify existing directories (unless whiteouts are enabled, then +directories are replaced)

+
 

OSTREE_REPO_CHECKOUT_OVERWRITE_ADD_FILES

+

Only add new files/directories

+
 

OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL

+

Like UNION_FILES, but error if files are not +identical (requires hardlink checkouts)

+
 
+
+
+
+
+

enum OstreeRepoListObjectsFlags

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_LIST_OBJECTS_LOOSE

+

List only loose (plain file) objects

+
 

OSTREE_REPO_LIST_OBJECTS_PACKED

+

List only packed (compacted into blobs) objects

+
 

OSTREE_REPO_LIST_OBJECTS_ALL

+

List all objects

+
 

OSTREE_REPO_LIST_OBJECTS_NO_PARENTS

+

Only list objects in this repo, not parents

+
 
+
+
+
+
+

OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE

+
#define OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE (G_VARIANT_TYPE ("(bas)")
+
+

b - TRUE if object is available "loose" +as - List of pack file checksums in which this object appears

+
+
+
+

enum OstreeStaticDeltaGenerateOpt

+

Parameters controlling optimization of static deltas.

+
+

Members

+
+++++ + + + + + + + + + + + + +

OSTREE_STATIC_DELTA_GENERATE_OPT_LOWLATENCY

+

Optimize for speed of delta creation over space

+
 

OSTREE_STATIC_DELTA_GENERATE_OPT_MAJOR

+

Optimize for delta size (may be very slow)

+
 
+
+
+
+
+

enum OstreeRepoCommitTraverseFlags

+
+

Members

+
+++++ + + + + + + + + + + + + +

OSTREE_REPO_COMMIT_TRAVERSE_FLAG_NONE

+

No special options for traverse

+
 

OSTREE_REPO_COMMIT_TRAVERSE_FLAG_COMMIT_ONLY

+

Traverse and retrieve only commit objects. +(Since: 2022.2)

+
 
+
+
+
+
+

enum OstreeRepoCommitIterResult

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_COMMIT_ITER_RESULT_ERROR

  

OSTREE_REPO_COMMIT_ITER_RESULT_END

  

OSTREE_REPO_COMMIT_ITER_RESULT_FILE

  

OSTREE_REPO_COMMIT_ITER_RESULT_DIR

  
+
+
+
+
+

enum OstreeRepoPruneFlags

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_PRUNE_FLAGS_NONE

+

No special options for pruning

+
 

OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE

+

Don't actually delete objects

+
 

OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY

+

Do not traverse individual commit objects, only follow refs +for reachability calculations

+
 

OSTREE_REPO_PRUNE_FLAGS_COMMIT_ONLY

+

Only traverse commit objects. (Since 2022.2)

+
 
+
+
+
+
+

enum OstreeRepoPullFlags

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_REPO_PULL_FLAGS_NONE

+

No special options for pull

+
 

OSTREE_REPO_PULL_FLAGS_MIRROR

+

Write out refs suitable for mirrors and fetch all refs if none +requested

+
 

OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY

+

Fetch only the commit metadata

+
 

OSTREE_REPO_PULL_FLAGS_UNTRUSTED

+

Do verify checksums of local (filesystem-accessible) +repositories (defaults on for HTTP)

+
 

OSTREE_REPO_PULL_FLAGS_BAREUSERONLY_FILES

+

Since 2017.7. Reject writes of content objects with +modes outside of 0775.

+
 

OSTREE_REPO_PULL_FLAGS_TRUSTED_HTTP

+

Don't verify checksums of objects HTTP repositories +(Since: 2017.12)

+
 
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-Progress-notification-system-for-asynchronous-operations.html b/reference/ostree-Progress-notification-system-for-asynchronous-operations.html new file mode 100644 index 0000000000..b0229a41ad --- /dev/null +++ b/reference/ostree-Progress-notification-system-for-asynchronous-operations.html @@ -0,0 +1,623 @@ + + + + +Progress notification system for asynchronous operations: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

Progress notification system for asynchronous operations

+

Progress notification system for asynchronous operations — Values representing progress

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+OstreeAsyncProgress * + +ostree_async_progress_new () +
+OstreeAsyncProgress * + +ostree_async_progress_new_and_connect () +
+void + +ostree_async_progress_copy_state () +
+char * + +ostree_async_progress_get_status () +
+void + +ostree_async_progress_get () +
+GVariant * + +ostree_async_progress_get_variant () +
+guint + +ostree_async_progress_get_uint () +
+guint64 + +ostree_async_progress_get_uint64 () +
+void + +ostree_async_progress_set_status () +
+void + +ostree_async_progress_set () +
+void + +ostree_async_progress_set_variant () +
+void + +ostree_async_progress_set_uint () +
+void + +ostree_async_progress_set_uint64 () +
+void + +ostree_async_progress_finish () +
+
+
+

Types and Values

+
++++ + + + + +
typedefOstreeAsyncProgress
+
+
+

Description

+

For many asynchronous operations, it's desirable for callers to be +able to watch their status as they progress. For example, an user +interface calling an asynchronous download operation will want to +be able to see the total number of bytes downloaded.

+

This class provides a mechanism for callees of asynchronous +operations to communicate back with callers. It transparently +handles thread safety, ensuring that the progress change +notification occurs in the thread-default context of the calling +operation.

+

The ostree_async_progress_get_status() and ostree_async_progress_set_status() +methods get and set a well-known status key of type G_VARIANT_TYPE_STRING. +This key may be accessed using the other OstreeAsyncProgress methods, but it +must always have the correct type.

+
+
+

Functions

+
+

ostree_async_progress_new ()

+
OstreeAsyncProgress *
+ostree_async_progress_new (void);
+
+

Returns

+

A new progress object.

+

[transfer full]

+
+
+
+
+

ostree_async_progress_new_and_connect ()

+
OstreeAsyncProgress *
+ostree_async_progress_new_and_connect (void (*changed) (OstreeAsyncProgress *self, gpointer user_data),
+                                       gpointer user_data);
+

[skip]

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

changed

a notification callback

 

user_data

data to pass to changed +

 
+
+
+

Returns

+

A new progress object.

+

[transfer full]

+
+
+
+
+

ostree_async_progress_copy_state ()

+
void
+ostree_async_progress_copy_state (OstreeAsyncProgress *self,
+                                  OstreeAsyncProgress *dest);
+

Atomically copies all the state from self + to dest +, without invoking the +callback. +This is used for proxying progress objects across different GMainContexts.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

An OstreeAsyncProgress to copy from

 

dest

An OstreeAsyncProgress to copy to

 
+
+

Since: 2019.6

+
+
+
+

ostree_async_progress_get_status ()

+
char *
+ostree_async_progress_get_status (OstreeAsyncProgress *self);
+

Get the human-readable status string from the OstreeAsyncProgress. This +operation is thread-safe. The retuned value may be NULL if no status is +set.

+

This is a convenience function to get the well-known status key.

+
+

Parameters

+
+++++ + + + + + +

self

an OstreeAsyncProgress

 
+
+
+

Returns

+

the current status, or NULL if none is set.

+

[transfer full][nullable]

+
+

Since: 2017.6

+
+
+
+

ostree_async_progress_get ()

+
void
+ostree_async_progress_get (OstreeAsyncProgress *self,
+                           ...);
+

Get the values corresponding to zero or more keys from the +OstreeAsyncProgress. Each key is specified in @... as the key name, followed +by a GVariant format string, followed by the necessary arguments for that +format string, just as for g_variant_get(). After those arguments is the +next key name. The varargs list must be NULL-terminated.

+

Each format string must make deep copies of its value, as the values stored +in the OstreeAsyncProgress may be freed from another thread after this +function returns.

+

This operation is thread-safe, and all the keys are queried atomically.

+
+ + + + + + + +
1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
guint32 outstanding_fetches;
+guint64 bytes_received;
+g_autofree gchar *status = NULL;
+g_autoptr(GVariant) refs_variant = NULL;
+
+ostree_async_progress_get (progress,
+                           "outstanding-fetches", "u", &outstanding_fetches,
+                           "bytes-received", "t", &bytes_received,
+                           "status", "s", &status,
+                           "refs", "@a{ss}", &refs_variant,
+                           NULL);
+
+ +

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

an OstreeAsyncProgress

 

...

key name, format string, GVariant return locations, …, followed by NULL

 
+
+

Since: 2017.6

+
+
+
+

ostree_async_progress_get_variant ()

+
GVariant *
+ostree_async_progress_get_variant (OstreeAsyncProgress *self,
+                                   const char *key);
+

Look up a key in the OstreeAsyncProgress and return the GVariant associated +with it. The lookup is thread-safe.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

an OstreeAsyncProgress

 

key

a key to look up

 
+
+
+

Returns

+

value for the given key +, or NULL if +it was not set.

+

[transfer full][nullable]

+
+

Since: 2017.6

+
+
+
+

ostree_async_progress_get_uint ()

+
guint
+ostree_async_progress_get_uint (OstreeAsyncProgress *self,
+                                const char *key);
+
+
+
+

ostree_async_progress_get_uint64 ()

+
guint64
+ostree_async_progress_get_uint64 (OstreeAsyncProgress *self,
+                                  const char *key);
+
+
+
+

ostree_async_progress_set_status ()

+
void
+ostree_async_progress_set_status (OstreeAsyncProgress *self,
+                                  const char *status);
+

Set the human-readable status string for the OstreeAsyncProgress. This +operation is thread-safe. NULL may be passed to clear the status.

+

This is a convenience function to set the well-known status key.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

an OstreeAsyncProgress

 

status

new status string, or NULL to clear the status.

[nullable]
+
+

Since: 2017.6

+
+
+
+

ostree_async_progress_set ()

+
void
+ostree_async_progress_set (OstreeAsyncProgress *self,
+                           ...);
+

Set the values for zero or more keys in the OstreeAsyncProgress. Each key is +specified in @... as the key name, followed by a GVariant format string, +followed by the necessary arguments for that format string, just as for +g_variant_new(). After those arguments is the next key name. The varargs list +must be NULL-terminated.

+

g_variant_ref_sink() will be called as appropriate on the GVariant +parameters, so they may be floating.

+

This operation is thread-safe, and all the keys are set atomically.

+
+ + + + + + + +
1
+2
+3
+4
+5
+6
+7
+8
+9
guint32 outstanding_fetches = 15;
+guint64 bytes_received = 1000;
+
+ostree_async_progress_set (progress,
+                           "outstanding-fetches", "u", outstanding_fetches,
+                           "bytes-received", "t", bytes_received,
+                           "status", "s", "Updated status",
+                           "refs", "@a{ss}", g_variant_new_parsed ("@a{ss} {}"),
+                           NULL);
+
+ +

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

an OstreeAsyncProgress

 

...

key name, format string, GVariant parameters, …, followed by NULL

 
+
+

Since: 2017.6

+
+
+
+

ostree_async_progress_set_variant ()

+
void
+ostree_async_progress_set_variant (OstreeAsyncProgress *self,
+                                   const char *key,
+                                   GVariant *value);
+

Assign a new value + to the given key +, replacing any existing value. The +operation is thread-safe. value + may be a floating reference; +g_variant_ref_sink() will be called on it.

+

Any watchers of the OstreeAsyncProgress will be notified of the change if +value + differs from the existing value for key +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeAsyncProgress

 

key

a key to set

 

value

the value to assign to key +

 
+
+

Since: 2017.6

+
+
+
+

ostree_async_progress_set_uint ()

+
void
+ostree_async_progress_set_uint (OstreeAsyncProgress *self,
+                                const char *key,
+                                guint value);
+
+
+
+

ostree_async_progress_set_uint64 ()

+
void
+ostree_async_progress_set_uint64 (OstreeAsyncProgress *self,
+                                  const char *key,
+                                  guint64 value);
+
+
+
+

ostree_async_progress_finish ()

+
void
+ostree_async_progress_finish (OstreeAsyncProgress *self);
+

Process any pending signals, ensuring the main context is cleared +of sources used by this object. Also ensures that no further +events will be queued.

+
+

Parameters

+
+++++ + + + + + +

self

Self

 
+
+
+
+
+

Types and Values

+
+

OstreeAsyncProgress

+
typedef struct OstreeAsyncProgress OstreeAsyncProgress;
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-Root-partition-mount-point.html b/reference/ostree-Root-partition-mount-point.html new file mode 100644 index 0000000000..28f2b9315d --- /dev/null +++ b/reference/ostree-Root-partition-mount-point.html @@ -0,0 +1,2586 @@ + + + + +Root partition mount point: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

Root partition mount point

+

Root partition mount point — Manage physical root filesystem

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+OstreeSysroot * + +ostree_sysroot_new () +
+OstreeSysroot * + +ostree_sysroot_new_default () +
+gboolean + +ostree_sysroot_initialize () +
+gboolean + +ostree_sysroot_initialize_with_mount_namespace () +
+GFile * + +ostree_sysroot_get_path () +
+gboolean + +ostree_sysroot_load () +
+gboolean + +ostree_sysroot_load_if_changed () +
+gboolean + +ostree_sysroot_lock () +
+gboolean + +ostree_sysroot_try_lock () +
+void + +ostree_sysroot_lock_async () +
+gboolean + +ostree_sysroot_lock_finish () +
+void + +ostree_sysroot_unlock () +
+void + +ostree_sysroot_unload () +
+gboolean + +ostree_sysroot_update_post_copy () +
+void + +ostree_sysroot_set_mount_namespace_in_use () +
+gboolean + +ostree_sysroot_is_booted () +
+int + +ostree_sysroot_get_fd () +
+gboolean + +ostree_sysroot_ensure_initialized () +
+int + +ostree_sysroot_get_bootversion () +
+int + +ostree_sysroot_get_subbootversion () +
+GPtrArray * + +ostree_sysroot_get_deployments () +
+OstreeDeployment * + +ostree_sysroot_get_booted_deployment () +
+OstreeDeployment * + +ostree_sysroot_require_booted_deployment () +
+GFile * + +ostree_sysroot_get_deployment_directory () +
+char * + +ostree_sysroot_get_deployment_dirpath () +
+GFile * + +ostree_sysroot_get_deployment_origin_path () +
+gboolean + +ostree_sysroot_cleanup () +
+gboolean + +ostree_sysroot_prepare_cleanup () +
+gboolean + +ostree_sysroot_cleanup_prune_repo () +
+OstreeRepo * + +ostree_sysroot_repo () +
+gboolean + +ostree_sysroot_get_repo () +
+OstreeDeployment * + +ostree_sysroot_get_staged_deployment () +
+gboolean + +ostree_sysroot_init_osname () +
+gboolean + +ostree_sysroot_deployment_set_kargs () +
+gboolean + +ostree_sysroot_deployment_set_kargs_in_place () +
+gboolean + +ostree_sysroot_deployment_set_mutable () +
+gboolean + +ostree_sysroot_deployment_unlock () +
+gboolean + +ostree_sysroot_deployment_set_pinned () +
+gboolean + +ostree_sysroot_write_deployments () +
+gboolean + +ostree_sysroot_write_deployments_with_options () +
+gboolean + +ostree_sysroot_write_origin_file () +
+gboolean + +ostree_sysroot_stage_tree () +
+gboolean + +ostree_sysroot_stage_tree_with_options () +
+gboolean + +ostree_sysroot_stage_overlay_initrd () +
+gboolean + +ostree_sysroot_change_finalization () +
+gboolean + +ostree_sysroot_deploy_tree () +
+gboolean + +ostree_sysroot_deploy_tree_with_options () +
+OstreeDeployment * + +ostree_sysroot_get_merge_deployment () +
+void + +ostree_sysroot_query_deployments_for () +
+GKeyFile * + +ostree_sysroot_origin_new_from_refspec () +
+gboolean + +ostree_sysroot_simple_write_deployment () +
+
+
+

Types and Values

+
++++ + + + + + + + + + + +
typedefOstreeSysroot
enumOstreeSysrootSimpleWriteDeploymentFlags
+
+
+

Description

+

A OstreeSysroot object represents a physical root filesystem, +which in particular should contain a toplevel /ostree directory. +Inside this directory is an OstreeRepo in /ostree/repo, plus a set +of deployments in /ostree/deploy.

+

This class is not by default safe against concurrent use by threads +or external processes. You can use ostree_sysroot_lock() to +perform locking externally.

+
+
+

Functions

+
+

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

+
+

Parameters

+
+++++ + + + + + +

path

Path to a system root directory, or NULL to use the +current visible root file system.

[allow-none]
+
+
+

Returns

+

An accessor object for an system root located at path +.

+

[transfer full]

+
+
+
+
+

ostree_sysroot_new_default ()

+
OstreeSysroot *
+ostree_sysroot_new_default (void);
+
+

Returns

+

An accessor for the current visible root / filesystem.

+

[transfer full]

+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + +

self

sysroot

 
+
+

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);
+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

Path to rootfs.

+

[transfer none][not nullable]

+
+
+
+
+

ostree_sysroot_load ()

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

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Sysroot

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_sysroot_load_if_changed ()

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

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

OstreeSysroot

 

out_changed

.

[out caller-allocates]

cancellable

Cancellable

 

error

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Self

 

error

Error

 
+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Self

 

out_acquired

Whether or not the lock has been acquired.

[out]

error

Error

 
+
+
+
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

cancellable

Cancellable

 

callback

Callback

 

user_data

User data

 
+
+
+
+
+

ostree_sysroot_lock_finish ()

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

Call when ostree_sysroot_lock_async() is ready.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Self

 

result

Result

 

error

Error

 
+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + +

self

Self

 
+
+
+
+
+

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

+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Sysroot

 

error

Error

 
+
+

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

+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

TRUE iff the sysroot points to a booted deployment

+
+

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.

+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

A file descriptor valid for the lifetime of self +

+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Sysroot

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

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);
+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

Ordered list of deployments.

+

[element-type OstreeDeployment][transfer container]

+
+
+
+
+

ostree_sysroot_get_booted_deployment ()

+
OstreeDeployment *
+ostree_sysroot_get_booted_deployment (OstreeSysroot *self);
+

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

+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

The currently booted deployment, or NULL if none.

+

[transfer none][nullable]

+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

The currently booted deployment, or an error.

+

[transfer none][not nullable]

+
+

Since: 2021.1

+
+
+
+

ostree_sysroot_get_deployment_directory ()

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

Parameters

+
+++++ + + + + + + + + + + + + +

self

Sysroot

 

deployment

A deployment

 
+
+
+

Returns

+

Path to deployment root directory.

+

[transfer full]

+
+
+
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Repo

 

deployment

A deployment

 
+
+
+

Returns

+

Path to deployment root directory, relative to sysroot.

+

[transfer full][not nullable]

+
+
+
+
+

ostree_sysroot_get_deployment_origin_path ()

+
GFile *
+ostree_sysroot_get_deployment_origin_path
+                               (GFile *deployment_path);
+
+

Parameters

+
+++++ + + + + + +

deployment_path

A deployment path

 
+
+
+

Returns

+

Path to deployment origin file.

+

[transfer full]

+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Sysroot

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Sysroot

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

sysroot

Sysroot

 

options

Flags controlling pruning

 

out_objects_total

Number of objects found.

[out]

out_objects_pruned

Number of objects deleted.

[out]

out_pruned_object_size_total

Storage size in bytes of objects deleted.

[out]

cancellable

Cancellable

 

error

Error

 
+
+

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.

+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

The OSTree repository in sysroot self +.

+

[transfer none][not nullable]

+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

out_repo

Repository in sysroot self +.

[out][transfer full][optional]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

TRUE on success, FALSE otherwise

+
+
+
+
+

ostree_sysroot_get_staged_deployment ()

+
OstreeDeployment *
+ostree_sysroot_get_staged_deployment (OstreeSysroot *self);
+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

The currently staged deployment, or NULL if none.

+

[transfer none][nullable]

+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

osname

Name group of operating system checkouts

 

cancellable

Cancellable

 

error

Error

 
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

deployment

A deployment

 

new_kargs

Replace deployment's kernel arguments.

[array zero-terminated=1][element-type utf8]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

deployment

A deployment

 

kargs_str

Replace deployment +'s kernel arguments.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

deployment

A deployment

 

is_mutable

Whether or not deployment's files can be changed

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

deployment

Deployment

 

unlocked_state

Transition to this unlocked state

 

cancellable

Cancellable

 

error

Error

 
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

deployment

A deployment

 

is_pinned

Whether or not deployment will be automatically GC'd

 

error

Error

 
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

new_deployments

List of new deployments.

[element-type OstreeDeployment]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

new_deployments

List of new deployments.

[element-type OstreeDeployment]

opts

Options

 

cancellable

Cancellable

 

error

Error

 
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

sysroot

System root

 

deployment

Deployment

 

new_origin

Origin content.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

osname

osname to use for merge deployment.

[allow-none]

revision

Checksum to add

 

origin

Origin to use for upgrades.

[allow-none]

merge_deployment

Use this deployment for merge path.

[allow-none]

override_kernel_argv

Use these as +kernel arguments; if NULL, inherit options from provided_merge_deployment.

[allow-none][array zero-terminated=1][element-type utf8]

out_new_deployment

The new deployment path.

[out]

cancellable

Cancellable

 

error

Error

 
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

osname

osname to use for merge deployment.

[allow-none]

revision

Checksum to add

 

origin

Origin to use for upgrades.

[allow-none]

merge_deployment

Use this deployment for merge path.

[allow-none]

opts

Options

 

out_new_deployment

The new deployment path.

[out]

cancellable

Cancellable

 

error

Error

 
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

fd

File descriptor to overlay initrd

 

out_checksum

Overlay initrd checksum.

[out][transfer full]

cancellable

Cancellable

 

error

Error

 
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Sysroot

 

deployment

Deployment which must be staged

 

error

Error

 
+
+

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

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

osname

osname to use for merge deployment.

[nullable]

revision

Checksum to add

 

origin

Origin to use for upgrades.

[nullable]

provided_merge_deployment

Use this deployment for merge path.

[nullable]

override_kernel_argv

Use these as +kernel arguments; if NULL, inherit options from provided_merge_deployment.

[nullable][array zero-terminated=1][element-type utf8]

out_new_deployment

The new deployment path.

[out]

cancellable

Cancellable

 

error

Error

 
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

osname

osname to use for merge deployment.

[nullable]

revision

Checksum to add

 

origin

Origin to use for upgrades.

[nullable]

provided_merge_deployment

Use this deployment for merge path.

[nullable]

opts

Options.

[nullable]

out_new_deployment

The new deployment path.

[out][transfer full]

cancellable

Cancellable

 

error

Error

 
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Sysroot

 

osname

Operating system group.

[allow-none]
+
+
+

Returns

+

Configuration merge deployment.

+

[transfer full][nullable]

+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

osname

"stateroot" name.

[allow-none]

out_pending

The pending deployment.

[out][nullable][optional][transfer full]

out_rollback

The rollback deployment.

[out][nullable][optional][transfer full]
+
+

Since: 2017.7

+
+
+
+

ostree_sysroot_origin_new_from_refspec ()

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

Parameters

+
+++++ + + + + + + + + + + + + +

self

Sysroot

 

refspec

A refspec

 
+
+
+

Returns

+

A new config file which sets refspec +as an origin.

+

[transfer full][not nullable]

+
+
+
+
+

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.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

sysroot

Sysroot

 

osname

OS name.

[allow-none]

new_deployment

Prepend this deployment to the list

 

merge_deployment

Use this deployment for configuration merge.

[allow-none]

flags

Flags controlling behavior

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

Types and Values

+
+

OstreeSysroot

+
typedef struct OstreeSysroot OstreeSysroot;
+
+
+
+
+

enum OstreeSysrootSimpleWriteDeploymentFlags

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NONE

  

OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN

  

OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT

  

OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN

  

OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING

  

OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK

  
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-SELinux-policy-management.html b/reference/ostree-SELinux-policy-management.html new file mode 100644 index 0000000000..116c2acf93 --- /dev/null +++ b/reference/ostree-SELinux-policy-management.html @@ -0,0 +1,566 @@ + + + + +SELinux policy management: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

SELinux policy management

+

SELinux policy management — Read SELinux policy and manage filesystem labels

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+OstreeSePolicy * + +ostree_sepolicy_new () +
+OstreeSePolicy * + +ostree_sepolicy_new_at () +
+OstreeSePolicy * + +ostree_sepolicy_new_from_commit () +
+GFile * + +ostree_sepolicy_get_path () +
const char * + +ostree_sepolicy_get_name () +
+gboolean + +ostree_sepolicy_get_label () +
const char * + +ostree_sepolicy_get_csum () +
+gboolean + +ostree_sepolicy_restorecon () +
+gboolean + +ostree_sepolicy_setfscreatecon () +
+void + +ostree_sepolicy_fscreatecon_cleanup () +
+
+
+

Types and Values

+
++++ + + + + + + + + + + +
typedefOstreeSePolicy
enumOstreeSePolicyRestoreconFlags
+
+
+

Description

+

A OstreeSePolicy object can load the SELinux policy from a given +root and perform labeling.

+
+
+

Functions

+
+

ostree_sepolicy_new ()

+
OstreeSePolicy *
+ostree_sepolicy_new (GFile *path,
+                     GCancellable *cancellable,
+                     GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

path

Path to a root directory

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

An accessor object for SELinux policy in root located at path +.

+

[transfer full]

+
+
+
+
+

ostree_sepolicy_new_at ()

+
OstreeSePolicy *
+ostree_sepolicy_new_at (int rootfs_dfd,
+                        GCancellable *cancellable,
+                        GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

rootfs_dfd

Directory fd for rootfs (will not be cloned)

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

An accessor object for SELinux policy in root located at rootfs_dfd +.

+

[transfer full]

+
+

Since: 2017.4

+
+
+
+

ostree_sepolicy_new_from_commit ()

+
OstreeSePolicy *
+ostree_sepolicy_new_from_commit (OstreeRepo *repo,
+                                 const char *rev,
+                                 GCancellable *cancellable,
+                                 GError **error);
+

Extract the SELinux policy from a commit object via a partial checkout. This is useful +for labeling derived content as separate commits.

+

This function is the backend of ostree_repo_commit_modifier_set_sepolicy_from_commit().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

repo

The repo

 

rev

ostree ref or checksum

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

A new policy.

+

[transfer full]

+
+
+
+
+

ostree_sepolicy_get_path ()

+
GFile *
+ostree_sepolicy_get_path (OstreeSePolicy *self);
+

This API should be considered deprecated, because it's supported for +policy objects to be created from file-descriptor relative paths, which +may not be globally accessible.

+
+

Parameters

+
+++++ + + + + + +

self

A SePolicy object

 
+
+
+

Returns

+

Path to rootfs.

+

[transfer none][nullable]

+
+
+
+
+

ostree_sepolicy_get_name ()

+
const char *
+ostree_sepolicy_get_name (OstreeSePolicy *self);
+
+

Returns

+

Type of current policy.

+

[transfer none]

+
+
+
+
+

ostree_sepolicy_get_label ()

+
gboolean
+ostree_sepolicy_get_label (OstreeSePolicy *self,
+                           const char *relpath,
+                           guint32 unix_mode,
+                           char **out_label,
+                           GCancellable *cancellable,
+                           GError **error);
+

Store in out_label + the security context for the given relpath + and +mode unix_mode +. If the policy does not specify a label, NULL +will be returned.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

relpath

Path

 

unix_mode

Unix mode

 

out_label

Return location for security context.

[nullable][out][transfer full]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_sepolicy_get_csum ()

+
const char *
+ostree_sepolicy_get_csum (OstreeSePolicy *self);
+
+

Returns

+

Checksum of current policy.

+

[transfer none][nullable]

+
+

Since: 2016.5

+
+
+
+

ostree_sepolicy_restorecon ()

+
gboolean
+ostree_sepolicy_restorecon (OstreeSePolicy *self,
+                            const char *path,
+                            GFileInfo *info,
+                            GFile *target,
+                            OstreeSePolicyRestoreconFlags flags,
+                            char **out_new_label,
+                            GCancellable *cancellable,
+                            GError **error);
+

Reset the security context of target + based on the SELinux policy.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

path

Path string to use for policy lookup

 

info

File attributes.

[nullable]

target

Physical path to target file

 

flags

Flags controlling behavior

 

out_new_label

New label, or NULL if unchanged.

[nullable][optional][out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_sepolicy_setfscreatecon ()

+
gboolean
+ostree_sepolicy_setfscreatecon (OstreeSePolicy *self,
+                                const char *path,
+                                guint32 mode,
+                                GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Policy

 

path

Use this path to determine a label

 

mode

Used along with path +

 

error

Error

 
+
+
+
+
+

ostree_sepolicy_fscreatecon_cleanup ()

+
void
+ostree_sepolicy_fscreatecon_cleanup (void **unused);
+

Cleanup function for ostree_sepolicy_setfscreatecon().

+
+

Parameters

+
+++++ + + + + + +

unused

Not used, just in case you didn't infer that from the parameter name

 
+
+
+
+
+

Types and Values

+
+

OstreeSePolicy

+
typedef struct OstreeSePolicy OstreeSePolicy;
+
+
+
+
+

enum OstreeSePolicyRestoreconFlags

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + +

OSTREE_SEPOLICY_RESTORECON_FLAGS_NONE

  

OSTREE_SEPOLICY_RESTORECON_FLAGS_ALLOW_NOLABEL

  

OSTREE_SEPOLICY_RESTORECON_FLAGS_KEEP_EXISTING

  
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-Signature-management.html b/reference/ostree-Signature-management.html new file mode 100644 index 0000000000..3ac4fce308 --- /dev/null +++ b/reference/ostree-Signature-management.html @@ -0,0 +1,878 @@ + + + + +Signature management: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

Signature management

+

Signature management — Sign and verify commits

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+GPtrArray * + +ostree_sign_get_all () +
+gboolean + +ostree_sign_commit () +
+gboolean + +ostree_sign_commit_verify () +
+gboolean + +ostree_sign_data () +
+gboolean + +ostree_sign_data_verify () +
+OstreeSign * + +ostree_sign_get_by_name () +
const gchar * + +ostree_sign_get_name () +
+gboolean + +ostree_sign_add_pk () +
+gboolean + +ostree_sign_clear_keys () +
+gboolean + +ostree_sign_load_pk () +
const gchar * + +ostree_sign_metadata_format () +
const gchar * + +ostree_sign_metadata_key () +
+gboolean + +ostree_sign_set_pk () +
+gboolean + +ostree_sign_set_sk () +
+gboolean + +ostree_sign_summary () +
+
+
+

Types and Values

+
++++ + + + + +
 OstreeSign
+
+
+

Description

+

An OstreeSign interface allows to select and use any available engine +for signing or verifying the commit object or summary file.

+
+
+

Functions

+
+

ostree_sign_get_all ()

+
GPtrArray *
+ostree_sign_get_all (void);
+

Return an array with newly allocated instances of all available +signing engines; they will not be initialized.

+
+

Returns

+

an array of signing engines.

+

[transfer full][element-type OstreeSign]

+
+

Since: 2020.2

+
+
+
+

ostree_sign_commit ()

+
gboolean
+ostree_sign_commit (OstreeSign *self,
+                    OstreeRepo *repo,
+                    const gchar *commit_checksum,
+                    GCancellable *cancellable,
+                    GError **error);
+

Add a signature to a commit.

+

Depending of the signing engine used you will need to load +the secret key with ostree_sign_set_sk.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeSign object

 

repo

an OsreeRepo object

 

commit_checksum

SHA256 of given commit to sign

 

cancellable

A GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE +if commit has been signed successfully, +FALSE +in case of error (error +will contain the reason).

+
+

Since: 2020.2

+
+
+
+

ostree_sign_commit_verify ()

+
gboolean
+ostree_sign_commit_verify (OstreeSign *self,
+                           OstreeRepo *repo,
+                           const gchar *commit_checksum,
+                           char **out_success_message,
+                           GCancellable *cancellable,
+                           GError **error);
+

Verify if commit is signed with known key.

+

Depending of the signing engine used you will need to load +the public key(s) for verification with ostree_sign_set_pk, +ostree_sign_add_pk and/or ostree_sign_load_pk.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeSign object

 

repo

an OsreeRepo object

 

commit_checksum

SHA256 of given commit to verify

 

out_success_message

success message returned by the signing +engine.

[out][nullable][optional]

cancellable

A GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE +if commit has been verified successfully, +FALSE +in case of error or no valid keys are available (error +will contain the reason).

+
+

Since: 2020.2

+
+
+
+

ostree_sign_data ()

+
gboolean
+ostree_sign_data (OstreeSign *self,
+                  GBytes *data,
+                  GBytes **signature,
+                  GCancellable *cancellable,
+                  GError **error);
+

Sign the given data + with pre-loaded secret key.

+

Depending of the signing engine used you will need to load +the secret key with ostree_sign_set_sk.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeSign object

 

data

the raw data to be signed with pre-loaded secret key

 

signature

in case of success will contain signature.

[out]

cancellable

A GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE +if data +has been signed successfully, +FALSE +in case of error (error +will contain the reason).

+
+

Since: 2020.2

+
+
+
+

ostree_sign_data_verify ()

+
gboolean
+ostree_sign_data_verify (OstreeSign *self,
+                         GBytes *data,
+                         GVariant *signatures,
+                         char **out_success_message,
+                         GError **error);
+

Verify given data against signatures with pre-loaded public keys.

+

Depending of the signing engine used you will need to load +the public key(s) with ostree_sign_set_pk, ostree_sign_add_pk +or ostree_sign_load_pk.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeSign object

 

data

the raw data to check

 

signatures

the signatures to be checked

 

out_success_message

success message returned by the signing +engine.

[out][nullable][optional]

error

a GError

 
+
+
+

Returns

+

TRUE +if data +has been signed at least with any single valid key, +FALSE +in case of error or no valid keys are available (error +will contain the reason).

+
+

Since: 2020.2

+
+
+
+

ostree_sign_get_by_name ()

+
OstreeSign *
+ostree_sign_get_by_name (const gchar *name,
+                         GError **error);
+

Create a new instance of a signing engine.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

name

the name of desired signature engine

 

error

return location for a GError

 
+
+
+

Returns

+

New signing engine, or NULL if the engine is not known.

+

[transfer full]

+
+

Since: 2020.2

+
+
+
+

ostree_sign_get_name ()

+
const gchar *
+ostree_sign_get_name (OstreeSign *self);
+

Return the pointer to the name of currently used/selected signing engine.

+
+

Parameters

+
+++++ + + + + + +

self

an OstreeSign object

 
+
+
+

Returns

+

pointer to the name +NULL +in case of error (unlikely).

+

[transfer none]

+
+

Since: 2020.2

+
+
+
+

ostree_sign_add_pk ()

+
gboolean
+ostree_sign_add_pk (OstreeSign *self,
+                    GVariant *public_key,
+                    GError **error);
+

Add the public key for verification. Could be called multiple times for +adding all needed keys to be used for verification.

+

The public_key + argument depends of the particular engine implementation.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeSign object

 

public_key

single public key to be added

 

error

a GError

 
+
+
+

Returns

+

TRUE +in case if the key could be added successfully, +FALSE +in case of error (error +will contain the reason).

+
+

Since: 2020.2

+
+
+
+

ostree_sign_clear_keys ()

+
gboolean
+ostree_sign_clear_keys (OstreeSign *self,
+                        GError **error);
+

Clear all previously preloaded secret and public keys.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

an OstreeSign object

 

error

a GError

 
+
+
+

Returns

+

TRUE +in case if no errors, FALSE +in case of error

+
+

Since: 2020.2

+
+
+
+

ostree_sign_load_pk ()

+
gboolean
+ostree_sign_load_pk (OstreeSign *self,
+                     GVariant *options,
+                     GError **error);
+

Load public keys for verification from anywhere. +It is expected that all keys would be added to already pre-loaded keys.

+

The options + argument depends of the particular engine implementation.

+

For example, ed25515 + engine could use following string-formatted options:

+
    +
  • filename + -- single file to use to load keys from

  • +
  • basedir + -- directory containing subdirectories +'trusted.ed25519.d' and 'revoked.ed25519.d' with appropriate +public keys. Used for testing and re-definition of system-wide +directories if defaults are not suitable for any reason.

  • +
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeSign object

 

options

any options

 

error

a GError

 
+
+
+

Returns

+

TRUE +in case if at least one key could be load successfully, +FALSE +in case of error (error +will contain the reason).

+
+

Since: 2020.2

+
+
+
+

ostree_sign_metadata_format ()

+
const gchar *
+ostree_sign_metadata_format (OstreeSign *self);
+

Return the pointer to the string with format used in (detached) metadata for +current signing engine.

+
+

Parameters

+
+++++ + + + + + +

self

an OstreeSign object

 
+
+
+

Returns

+

pointer to the metadata format, +NULL +in case of error (unlikely).

+

[transfer none]

+
+

Since: 2020.2

+
+
+
+

ostree_sign_metadata_key ()

+
const gchar *
+ostree_sign_metadata_key (OstreeSign *self);
+

Return the pointer to the name of the key used in (detached) metadata for +current signing engine.

+
+

Parameters

+
+++++ + + + + + +

self

an OstreeSign object

 
+
+
+

Returns

+

pointer to the metadata key name, +NULL +in case of error (unlikely).

+

[transfer none]

+
+

Since: 2020.2

+
+
+
+

ostree_sign_set_pk ()

+
gboolean
+ostree_sign_set_pk (OstreeSign *self,
+                    GVariant *public_key,
+                    GError **error);
+

Set the public key for verification. It is expected what all +previously pre-loaded public keys will be dropped.

+

The public_key + argument depends of the particular engine implementation.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeSign object

 

public_key

single public key to be added

 

error

a GError

 
+
+
+

Returns

+

TRUE +in case if the key could be set successfully, +FALSE +in case of error (error +will contain the reason).

+
+

Since: 2020.2

+
+
+
+

ostree_sign_set_sk ()

+
gboolean
+ostree_sign_set_sk (OstreeSign *self,
+                    GVariant *secret_key,
+                    GError **error);
+

Set the secret key to be used for signing data, commits and summary.

+

The secret_key + argument depends of the particular engine implementation.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeSign object

 

secret_key

secret key to be added

 

error

a GError

 
+
+
+

Returns

+

TRUE +in case if the key could be set successfully, +FALSE +in case of error (error +will contain the reason).

+
+

Since: 2020.2

+
+
+
+

ostree_sign_summary ()

+
gboolean
+ostree_sign_summary (OstreeSign *self,
+                     OstreeRepo *repo,
+                     GVariant *keys,
+                     GCancellable *cancellable,
+                     GError **error);
+

Add a signature to a summary file. +Based on ostree_repo_add_gpg_signature_summary implementation.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Self

 

repo

ostree repository

 

keys

keys -- GVariant containing keys as GVarints specific to signature type.

 

cancellable

A GCancellable

 

error

a GError

 
+
+
+

Returns

+

TRUE +if summary file has been signed with all provided keys

+
+

Since: 2020.2

+
+
+
+

Types and Values

+
+

OstreeSign

+
typedef struct _OstreeSign OstreeSign;
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-Simple-upgrade-class.html b/reference/ostree-Simple-upgrade-class.html new file mode 100644 index 0000000000..346ffd4023 --- /dev/null +++ b/reference/ostree-Simple-upgrade-class.html @@ -0,0 +1,726 @@ + + + + +Simple upgrade class: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

Simple upgrade class

+

Simple upgrade class — Upgrade OSTree systems

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+OstreeSysrootUpgrader * + +ostree_sysroot_upgrader_new () +
+OstreeSysrootUpgrader * + +ostree_sysroot_upgrader_new_for_os () +
+OstreeSysrootUpgrader * + +ostree_sysroot_upgrader_new_for_os_with_flags () +
+GKeyFile * + +ostree_sysroot_upgrader_get_origin () +
+GKeyFile * + +ostree_sysroot_upgrader_dup_origin () +
+gboolean + +ostree_sysroot_upgrader_set_origin () +
+char * + +ostree_sysroot_upgrader_get_origin_description () +
+gboolean + +ostree_sysroot_upgrader_check_timestamps () +
+gboolean + +ostree_sysroot_upgrader_pull () +
+gboolean + +ostree_sysroot_upgrader_pull_one_dir () +
+gboolean + +ostree_sysroot_upgrader_deploy () +
+
+
+

Types and Values

+ +
+
+

Description

+

The OstreeSysrootUpgrader class allows performing simple upgrade +operations.

+
+
+

Functions

+
+

ostree_sysroot_upgrader_new ()

+
OstreeSysrootUpgrader *
+ostree_sysroot_upgrader_new (OstreeSysroot *sysroot,
+                             GCancellable *cancellable,
+                             GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

sysroot

An OstreeSysroot

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

An upgrader.

+

[transfer full]

+
+
+
+
+

ostree_sysroot_upgrader_new_for_os ()

+
OstreeSysrootUpgrader *
+ostree_sysroot_upgrader_new_for_os (OstreeSysroot *sysroot,
+                                    const char *osname,
+                                    GCancellable *cancellable,
+                                    GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

sysroot

An OstreeSysroot

 

osname

Operating system name.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

An upgrader.

+

[transfer full]

+
+
+
+
+

ostree_sysroot_upgrader_new_for_os_with_flags ()

+
OstreeSysrootUpgrader *
+ostree_sysroot_upgrader_new_for_os_with_flags
+                               (OstreeSysroot *sysroot,
+                                const char *osname,
+                                OstreeSysrootUpgraderFlags flags,
+                                GCancellable *cancellable,
+                                GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

sysroot

An OstreeSysroot

 

osname

Operating system name.

[allow-none]

flags

Flags

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

An upgrader.

+

[transfer full]

+
+
+
+
+

ostree_sysroot_upgrader_get_origin ()

+
GKeyFile *
+ostree_sysroot_upgrader_get_origin (OstreeSysrootUpgrader *self);
+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

The origin file, or NULL if unknown.

+

[transfer none][nullable]

+
+
+
+
+

ostree_sysroot_upgrader_dup_origin ()

+
GKeyFile *
+ostree_sysroot_upgrader_dup_origin (OstreeSysrootUpgrader *self);
+
+

Parameters

+
+++++ + + + + + +

self

Sysroot

 
+
+
+

Returns

+

A copy of the origin file, or NULL if unknown.

+

[transfer full][nullable]

+
+
+
+
+

ostree_sysroot_upgrader_set_origin ()

+
gboolean
+ostree_sysroot_upgrader_set_origin (OstreeSysrootUpgrader *self,
+                                    GKeyFile *origin,
+                                    GCancellable *cancellable,
+                                    GError **error);
+

Replace the origin with origin +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

Sysroot

 

origin

The new origin.

[allow-none]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_sysroot_upgrader_get_origin_description ()

+
char *
+ostree_sysroot_upgrader_get_origin_description
+                               (OstreeSysrootUpgrader *self);
+
+

Parameters

+
+++++ + + + + + +

self

Upgrader

 
+
+
+

Returns

+

A one-line descriptive summary of the origin, or NULL if +unknown.

+

[transfer full][nullable]

+
+
+
+
+

ostree_sysroot_upgrader_check_timestamps ()

+
gboolean
+ostree_sysroot_upgrader_check_timestamps
+                               (OstreeRepo *repo,
+                                const char *from_rev,
+                                const char *to_rev,
+                                GError **error);
+

Check that the timestamp on to_rev + is equal to or newer than +from_rev +. This protects systems against man-in-the-middle +attackers which provide a client with an older commit.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

repo

Repo

 

from_rev

From revision

 

to_rev

To revision

 

error

Error

 
+
+
+
+
+

ostree_sysroot_upgrader_pull ()

+
gboolean
+ostree_sysroot_upgrader_pull (OstreeSysrootUpgrader *self,
+                              OstreeRepoPullFlags flags,
+                              OstreeSysrootUpgraderPullFlags upgrader_flags,
+                              OstreeAsyncProgress *progress,
+                              gboolean *out_changed,
+                              GCancellable *cancellable,
+                              GError **error);
+

Perform a pull from the origin. First check if the ref has +changed, if so download the linked objects, and store the updated +ref locally. Then out_changed + will be TRUE.

+

If the origin remote is unchanged, out_changed + will be set to +FALSE.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Upgrader

 

flags

Flags controlling pull behavior

 

upgrader_flags

Flags controlling upgrader behavior

 

progress

Progress.

[allow-none]

out_changed

Whether or not the origin changed.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_sysroot_upgrader_pull_one_dir ()

+
gboolean
+ostree_sysroot_upgrader_pull_one_dir (OstreeSysrootUpgrader *self,
+                                      const char *dir_to_pull,
+                                      OstreeRepoPullFlags flags,
+                                      OstreeSysrootUpgraderPullFlags upgrader_flags,
+                                      OstreeAsyncProgress *progress,
+                                      gboolean *out_changed,
+                                      GCancellable *cancellable,
+                                      GError **error);
+

Like ostree_sysroot_upgrader_pull(), but allows retrieving just a +subpath of the tree. This can be used to download metadata files +from inside the tree such as package databases.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Upgrader

 

dir_to_pull

Subdirectory path (should include a leading /)

 

flags

Flags controlling pull behavior

 

upgrader_flags

Flags controlling upgrader behavior

 

progress

Progress.

[allow-none]

out_changed

Whether or not the origin changed.

[out]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_sysroot_upgrader_deploy ()

+
gboolean
+ostree_sysroot_upgrader_deploy (OstreeSysrootUpgrader *self,
+                                GCancellable *cancellable,
+                                GError **error);
+

Write the new deployment to disk, perform a configuration merge +with /etc, and update the bootloader configuration.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Self

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

Types and Values

+
+

OstreeSysrootUpgrader

+
typedef struct OstreeSysrootUpgrader OstreeSysrootUpgrader;
+
+
+
+
+

enum OstreeSysrootUpgraderFlags

+

Flags controlling operation of an OstreeSysrootUpgrader.

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + +

OSTREE_SYSROOT_UPGRADER_FLAGS_NONE

+

No options

+
 

OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED

+

Do not error if the origin has an +unconfigured-state key

+
 

OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE

+

Enable "staging" (finalization at shutdown); recommended +(Since: 2021.4)

+
 
+
+
+
+
+

enum OstreeSysrootUpgraderPullFlags

+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + +

OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_NONE

  

OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_ALLOW_OLDER

  

OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_SYNTHETIC

  
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-bootconfig-parser.html b/reference/ostree-ostree-bootconfig-parser.html new file mode 100644 index 0000000000..9cda254801 --- /dev/null +++ b/reference/ostree-ostree-bootconfig-parser.html @@ -0,0 +1,400 @@ + + + + +ostree-bootconfig-parser: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-bootconfig-parser

+

ostree-bootconfig-parser

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+OstreeBootconfigParser * + +ostree_bootconfig_parser_new () +
+OstreeBootconfigParser * + +ostree_bootconfig_parser_clone () +
+gboolean + +ostree_bootconfig_parser_parse () +
+gboolean + +ostree_bootconfig_parser_parse_at () +
+gboolean + +ostree_bootconfig_parser_write () +
+gboolean + +ostree_bootconfig_parser_write_at () +
+void + +ostree_bootconfig_parser_set () +
const char * + +ostree_bootconfig_parser_get () +
+void + +ostree_bootconfig_parser_set_overlay_initrds () +
+char ** + +ostree_bootconfig_parser_get_overlay_initrds () +
+
+
+

Types and Values

+
++++ + + + + +
 OstreeBootconfigParser
+
+
+

Description

+
+
+

Functions

+
+

ostree_bootconfig_parser_new ()

+
OstreeBootconfigParser *
+ostree_bootconfig_parser_new (void);
+
+
+
+

ostree_bootconfig_parser_clone ()

+
OstreeBootconfigParser *
+ostree_bootconfig_parser_clone (OstreeBootconfigParser *self);
+
+

Parameters

+
+++++ + + + + + +

self

Bootconfig to clone

 
+
+
+

Returns

+

Copy of self +.

+

[transfer full]

+
+
+
+
+

ostree_bootconfig_parser_parse ()

+
gboolean
+ostree_bootconfig_parser_parse (OstreeBootconfigParser *self,
+                                GFile *path,
+                                GCancellable *cancellable,
+                                GError **error);
+
+
+
+

ostree_bootconfig_parser_parse_at ()

+
gboolean
+ostree_bootconfig_parser_parse_at (OstreeBootconfigParser *self,
+                                   int dfd,
+                                   const char *path,
+                                   GCancellable *cancellable,
+                                   GError **error);
+

Initialize a bootconfig from the given file.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

Parser

 

dfd

Directory fd

 

path

File path

 

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_bootconfig_parser_write ()

+
gboolean
+ostree_bootconfig_parser_write (OstreeBootconfigParser *self,
+                                GFile *output,
+                                GCancellable *cancellable,
+                                GError **error);
+
+
+
+

ostree_bootconfig_parser_write_at ()

+
gboolean
+ostree_bootconfig_parser_write_at (OstreeBootconfigParser *self,
+                                   int dfd,
+                                   const char *path,
+                                   GCancellable *cancellable,
+                                   GError **error);
+
+
+
+

ostree_bootconfig_parser_set ()

+
void
+ostree_bootconfig_parser_set (OstreeBootconfigParser *self,
+                              const char *key,
+                              const char *value);
+

Set the key +/value + pair to the boot configuration dictionary.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Parser

 

key

the key

 

value

the key

 
+
+
+
+
+

ostree_bootconfig_parser_get ()

+
const char *
+ostree_bootconfig_parser_get (OstreeBootconfigParser *self,
+                              const char *key);
+

Get the value corresponding to key + from the boot configuration dictionary.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Parser

 

key

the key name to retrieve

 
+
+
+

Returns

+

The corresponding value, or NULL if the key hasn't been +found.

+

[nullable]

+
+
+
+
+

ostree_bootconfig_parser_set_overlay_initrds ()

+
void
+ostree_bootconfig_parser_set_overlay_initrds
+                               (OstreeBootconfigParser *self,
+                                char **initrds);
+

These are rendered as additional initrd keys in the final bootloader configs. The +base initrd is part of the primary keys.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Parser

 

initrds

Array of overlay +initrds or NULL to unset.

[array zero-terminated=1][transfer none][allow-none]
+
+

Since: 2020.7

+
+
+
+

ostree_bootconfig_parser_get_overlay_initrds ()

+
char **
+ostree_bootconfig_parser_get_overlay_initrds
+                               (OstreeBootconfigParser *self);
+
+

Parameters

+
+++++ + + + + + +

self

Parser

 
+
+
+

Returns

+

Array of initrds or NULL +if none are set.

+

[array zero-terminated=1][transfer none][nullable]

+
+

Since: 2020.7

+
+
+
+

Types and Values

+
+

OstreeBootconfigParser

+
typedef struct _OstreeBootconfigParser OstreeBootconfigParser;
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-chain-input-stream.html b/reference/ostree-ostree-chain-input-stream.html new file mode 100644 index 0000000000..8f5262a3ac --- /dev/null +++ b/reference/ostree-ostree-chain-input-stream.html @@ -0,0 +1,89 @@ + + + + +ostree-chain-input-stream: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-chain-input-stream

+

ostree-chain-input-stream

+
+
+

Functions

+ +
+
+

Types and Values

+
++++ + + + + +
structOstreeChainInputStream
+
+
+

Description

+
+
+

Functions

+
+

ostree_chain_input_stream_new ()

+
OstreeChainInputStream *
+ostree_chain_input_stream_new (GPtrArray *streams);
+
+
+
+

Types and Values

+
+

struct OstreeChainInputStream

+
struct OstreeChainInputStream {
+  GInputStream parent_instance;
+};
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-checksum-input-stream.html b/reference/ostree-ostree-checksum-input-stream.html new file mode 100644 index 0000000000..72e2a30d38 --- /dev/null +++ b/reference/ostree-ostree-checksum-input-stream.html @@ -0,0 +1,90 @@ + + + + +ostree-checksum-input-stream: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-checksum-input-stream

+

ostree-checksum-input-stream

+
+
+

Functions

+ +
+
+

Types and Values

+
++++ + + + + +
structOstreeChecksumInputStream
+
+
+

Description

+
+
+

Functions

+
+

ostree_checksum_input_stream_new ()

+
OstreeChecksumInputStream *
+ostree_checksum_input_stream_new (GInputStream *stream,
+                                  GChecksum *checksum);
+
+
+
+

Types and Values

+
+

struct OstreeChecksumInputStream

+
struct OstreeChecksumInputStream {
+  GFilterInputStream parent_instance;
+};
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-content-writer.html b/reference/ostree-ostree-content-writer.html new file mode 100644 index 0000000000..406f81dc3d --- /dev/null +++ b/reference/ostree-ostree-content-writer.html @@ -0,0 +1,101 @@ + + + + +ostree-content-writer: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-content-writer

+

ostree-content-writer

+
+
+

Functions

+
++++ + + + + +
+char * + +ostree_content_writer_finish () +
+
+
+

Description

+
+
+

Functions

+
+

ostree_content_writer_finish ()

+
char *
+ostree_content_writer_finish (OstreeContentWriter *self,
+                              GCancellable *cancellable,
+                              GError **error);
+

Complete the object write and return the checksum.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

Writer

 

cancellable

Cancellable

 

error

Error

 
+
+
+

Returns

+

Checksum, or NULL on error.

+

[transfer full]

+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-deployment.html b/reference/ostree-ostree-deployment.html new file mode 100644 index 0000000000..4ef84dce5b --- /dev/null +++ b/reference/ostree-ostree-deployment.html @@ -0,0 +1,884 @@ + + + + +ostree-deployment: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-deployment

+

ostree-deployment

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+guint + +ostree_deployment_hash () +
+gboolean + +ostree_deployment_equal () +
+OstreeDeployment * + +ostree_deployment_new () +
+int + +ostree_deployment_get_index () +
const char * + +ostree_deployment_get_osname () +
+int + +ostree_deployment_get_deployserial () +
const char * + +ostree_deployment_get_csum () +
const char * + +ostree_deployment_get_bootcsum () +
+int + +ostree_deployment_get_bootserial () +
+OstreeBootconfigParser * + +ostree_deployment_get_bootconfig () +
+GKeyFile * + +ostree_deployment_get_origin () +
+char * + +ostree_deployment_get_origin_relpath () +
+OstreeDeploymentUnlockedState + +ostree_deployment_get_unlocked () +
+gboolean + +ostree_deployment_is_pinned () +
+gboolean + +ostree_deployment_is_staged () +
+gboolean + +ostree_deployment_is_finalization_locked () +
+void + +ostree_deployment_set_index () +
+void + +ostree_deployment_set_bootserial () +
+void + +ostree_deployment_set_bootconfig () +
+void + +ostree_deployment_set_origin () +
+void + +ostree_deployment_origin_remove_transient_state () +
+OstreeDeployment * + +ostree_deployment_clone () +
const char * + +ostree_deployment_unlocked_state_to_string () +
+
+
+

Types and Values

+
++++ + + + + +
 OstreeDeployment
+
+
+

Description

+
+
+

Functions

+
+

ostree_deployment_hash ()

+
guint
+ostree_deployment_hash (gconstpointer v);
+
+

Parameters

+
+++++ + + + + + +

v

Deployment.

[type OstreeDeployment]
+
+
+

Returns

+

An integer suitable for use in a GHashTable

+
+
+
+
+

ostree_deployment_equal ()

+
gboolean
+ostree_deployment_equal (gconstpointer ap,
+                         gconstpointer bp);
+
+

Parameters

+
+++++ + + + + + + + + + + + + +

ap

A deployment.

[type OstreeDeployment]

bp

A deployment.

[type OstreeDeployment]
+
+
+

Returns

+

TRUE if deployments have the same osname, csum, and deployserial

+
+
+
+
+

ostree_deployment_new ()

+
OstreeDeployment *
+ostree_deployment_new (int index,
+                       const char *osname,
+                       const char *csum,
+                       int deployserial,
+                       const char *bootcsum,
+                       int bootserial);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

index

Global index into the bootloader entries

 

osname

"stateroot" for this deployment

 

csum

OSTree commit that will be deployed

 

deployserial

Unique counter

 

bootcsum

Kernel/initrd checksum.

[nullable]

bootserial

Unique index

 
+
+
+

Returns

+

New deployment.

+

[transfer full][not nullable]

+
+
+
+
+

ostree_deployment_get_index ()

+
int
+ostree_deployment_get_index (OstreeDeployment *self);
+
+

Parameters

+
+++++ + + + + + +

self

Deployment

 
+
+
+

Returns

+

The global index into the bootloader ordering

+
+
+
+
+

ostree_deployment_get_osname ()

+
const char *
+ostree_deployment_get_osname (OstreeDeployment *self);
+
+
+
+

ostree_deployment_get_deployserial ()

+
int
+ostree_deployment_get_deployserial (OstreeDeployment *self);
+
+
+
+

ostree_deployment_get_csum ()

+
const char *
+ostree_deployment_get_csum (OstreeDeployment *self);
+
+
+
+

ostree_deployment_get_bootcsum ()

+
const char *
+ostree_deployment_get_bootcsum (OstreeDeployment *self);
+
+
+
+

ostree_deployment_get_bootserial ()

+
int
+ostree_deployment_get_bootserial (OstreeDeployment *self);
+
+
+
+

ostree_deployment_get_bootconfig ()

+
OstreeBootconfigParser *
+ostree_deployment_get_bootconfig (OstreeDeployment *self);
+
+

Parameters

+
+++++ + + + + + +

self

Deployment

 
+
+
+

Returns

+

Boot configuration.

+

[transfer none][nullable]

+
+
+
+
+

ostree_deployment_get_origin ()

+
GKeyFile *
+ostree_deployment_get_origin (OstreeDeployment *self);
+
+

Parameters

+
+++++ + + + + + +

self

Deployment

 
+
+
+

Returns

+

Origin.

+

[transfer none][nullable]

+
+
+
+
+

ostree_deployment_get_origin_relpath ()

+
char *
+ostree_deployment_get_origin_relpath (OstreeDeployment *self);
+

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

+
+

Parameters

+
+++++ + + + + + +

self

A deployment

 
+
+
+

Returns

+

Path to deployment root directory, relative to sysroot.

+

[not nullable][transfer full]

+
+
+
+
+

ostree_deployment_get_unlocked ()

+
OstreeDeploymentUnlockedState
+ostree_deployment_get_unlocked (OstreeDeployment *self);
+

Since: 2016.4

+
+
+
+

ostree_deployment_is_pinned ()

+
gboolean
+ostree_deployment_is_pinned (OstreeDeployment *self);
+

See ostree_sysroot_deployment_set_pinned().

+
+

Parameters

+
+++++ + + + + + +

self

Deployment

 
+
+
+

Returns

+

TRUE if deployment will not be subject to GC

+
+

Since: 2018.3

+
+
+
+

ostree_deployment_is_staged ()

+
gboolean
+ostree_deployment_is_staged (OstreeDeployment *self);
+
+

Parameters

+
+++++ + + + + + +

self

Deployment

 
+
+
+

Returns

+

TRUE if deployment should be "finalized" at shutdown time

+
+

Since: 2018.3

+
+
+
+

ostree_deployment_is_finalization_locked ()

+
gboolean
+ostree_deployment_is_finalization_locked
+                               (OstreeDeployment *self);
+
+

Parameters

+
+++++ + + + + + +

self

Deployment

 
+
+
+

Returns

+

TRUE if deployment is queued to be "finalized" at shutdown time, but requires +additional action.

+
+

Since: 2023.8

+
+
+
+

ostree_deployment_set_index ()

+
void
+ostree_deployment_set_index (OstreeDeployment *self,
+                             int index);
+

Sets the global index into the bootloader ordering.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Deployment

 

index

Index into bootloader ordering

 
+
+
+
+
+

ostree_deployment_set_bootserial ()

+
void
+ostree_deployment_set_bootserial (OstreeDeployment *self,
+                                  int index);
+

Should never have been made public API; don't use this.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Deployment

 

index

Don't use this

 
+
+
+
+
+

ostree_deployment_set_bootconfig ()

+
void
+ostree_deployment_set_bootconfig (OstreeDeployment *self,
+                                  OstreeBootconfigParser *bootconfig);
+

Set or clear the bootloader configuration.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Deployment

 

bootconfig

Bootloader configuration object.

[nullable]
+
+
+
+
+

ostree_deployment_set_origin ()

+
void
+ostree_deployment_set_origin (OstreeDeployment *self,
+                              GKeyFile *origin);
+

Replace the "origin", which is a description of the source +of the deployment and how to update to the next version.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

Deployment

 

origin

Set the origin for this deployment.

[nullable]
+
+
+
+
+

ostree_deployment_origin_remove_transient_state ()

+
void
+ostree_deployment_origin_remove_transient_state
+                               (GKeyFile *origin);
+

The intention of an origin file is primarily describe the "inputs" that +resulted in a deployment, and it's commonly used to derive the new state. For +example, a key value (in pure libostree mode) is the "refspec". However, +libostree (or other applications) may want to store "transient" state that +should not be carried across upgrades.

+

This function just removes all members of the libostree-transient group. +The name of that group is available to all libostree users; best practice +would be to prefix values underneath there with a short identifier for your +software.

+

Additionally, this function will remove the origin/unlocked and +origin/override-commit members; these should be considered transient state +that should have been under an explicit group.

+
+

Parameters

+
+++++ + + + + + +

origin

An origin

 
+
+

Since: 2018.3

+
+
+
+

ostree_deployment_clone ()

+
OstreeDeployment *
+ostree_deployment_clone (OstreeDeployment *self);
+
+

Parameters

+
+++++ + + + + + +

self

Deployment

 
+
+
+

Returns

+

New deep copy of self +.

+

[not nullable][transfer full]

+
+
+
+
+

ostree_deployment_unlocked_state_to_string ()

+
const char *
+ostree_deployment_unlocked_state_to_string
+                               (OstreeDeploymentUnlockedState state);
+
+

Returns

+

Description of state.

+

[not nullable]

+
+

Since: 2016.4

+
+
+
+

Types and Values

+
+

OstreeDeployment

+
typedef struct {
+  GObject parent_instance;
+
+  int index;
+  char *osname;
+  char *csum;
+  int deployserial;
+  char *bootcsum;
+  int bootserial;
+  OstreeBootconfigParser *bootconfig;
+  GKeyFile *origin;
+  OstreeDeploymentUnlockedState unlocked;
+  gboolean staged;
+  gboolean finalization_locked;
+  char **overlay_initrds;
+  char *overlay_initrds_id;
+} OstreeDeployment;
+
+
+

Members

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

int index;

Global offset

 

char *osname;

  

char *csum;

OSTree checksum of tree

 

int deployserial;

How many times this particular csum appears in deployment list

 

char *bootcsum;

Checksum of kernel+initramfs

 

int bootserial;

An integer assigned to this tree per its ${bootcsum}

 

OstreeBootconfigParser *bootconfig;

Bootloader configuration

 

GKeyFile *origin;

How to construct an upgraded version of this tree

 

OstreeDeploymentUnlockedState unlocked;

The unlocked state

 

gboolean staged;

TRUE iff this deployment is staged

 

gboolean finalization_locked;

  

char **overlay_initrds;

Checksums of staged additional initrds for this deployment

 

char *overlay_initrds_id;

Unique ID generated from initrd checksums; used to compare deployments

 
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-diff.html b/reference/ostree-ostree-diff.html new file mode 100644 index 0000000000..a6b31877df --- /dev/null +++ b/reference/ostree-ostree-diff.html @@ -0,0 +1,369 @@ + + + + +ostree-diff: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-diff

+

ostree-diff

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + +
+OstreeDiffItem * + +ostree_diff_item_ref () +
+void + +ostree_diff_item_unref () +
+gboolean + +ostree_diff_dirs () +
+gboolean + +ostree_diff_dirs_with_options () +
+void + +ostree_diff_print () +
+
+
+

Types and Values

+
++++ + + + + + + + + + + +
enumOstreeDiffFlags
structOstreeDiffItem
+
+
+

Description

+
+
+

Functions

+
+

ostree_diff_item_ref ()

+
OstreeDiffItem *
+ostree_diff_item_ref (OstreeDiffItem *diffitem);
+
+
+
+

ostree_diff_item_unref ()

+
void
+ostree_diff_item_unref (OstreeDiffItem *diffitem);
+
+
+
+

ostree_diff_dirs ()

+
gboolean
+ostree_diff_dirs (OstreeDiffFlags flags,
+                  GFile *a,
+                  GFile *b,
+                  GPtrArray *modified,
+                  GPtrArray *removed,
+                  GPtrArray *added,
+                  GCancellable *cancellable,
+                  GError **error);
+

Compute the difference between directory a + and b + as 3 separate +sets of OstreeDiffItem in modified +, removed +, and added +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

flags

Flags

 

a

First directory path, or NULL

 

b

First directory path

 

modified

Modified files.

[element-type OstreeDiffItem]

removed

Removed files.

[element-type Gio.File]

added

Added files.

[element-type Gio.File]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_diff_dirs_with_options ()

+
gboolean
+ostree_diff_dirs_with_options (OstreeDiffFlags flags,
+                               GFile *a,
+                               GFile *b,
+                               GPtrArray *modified,
+                               GPtrArray *removed,
+                               GPtrArray *added,
+                               OstreeDiffDirsOptions *options,
+                               GCancellable *cancellable,
+                               GError **error);
+

Compute the difference between directory a + and b + as 3 separate +sets of OstreeDiffItem in modified +, removed +, and added +.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

flags

Flags

 

a

First directory path, or NULL

 

b

First directory path

 

modified

Modified files.

[element-type OstreeDiffItem]

removed

Removed files.

[element-type Gio.File]

added

Added files.

[element-type Gio.File]

cancellable

Cancellable

 

options

Options.

[allow-none]

error

Error

 
+
+

Since: 2017.4

+
+
+
+

ostree_diff_print ()

+
void
+ostree_diff_print (GFile *a,
+                   GFile *b,
+                   GPtrArray *modified,
+                   GPtrArray *removed,
+                   GPtrArray *added);
+

Print the contents of a diff to stdout.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

a

First directory path

 

b

First directory path

 

modified

Modified files.

[element-type OstreeDiffItem]

removed

Removed files.

[element-type Gio.File]

added

Added files.

[element-type Gio.File]
+
+
+
+
+

Types and Values

+
+

enum OstreeDiffFlags

+
+

Members

+
+++++ + + + + + + + + + + + + +

OSTREE_DIFF_FLAGS_NONE

  

OSTREE_DIFF_FLAGS_IGNORE_XATTRS

  
+
+
+
+
+

struct OstreeDiffItem

+
struct OstreeDiffItem {
+  gint refcount; /* atomic */
+
+  GFile *src;
+  GFile *target;
+
+  GFileInfo *src_info;
+  GFileInfo *target_info;
+
+  char *src_checksum;
+  char *target_checksum;
+};
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-kernel-args.html b/reference/ostree-ostree-kernel-args.html new file mode 100644 index 0000000000..1708a69006 --- /dev/null +++ b/reference/ostree-ostree-kernel-args.html @@ -0,0 +1,1005 @@ + + + + +ostree-kernel-args: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-kernel-args

+

ostree-kernel-args

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+void + +ostree_kernel_args_free () +
+OstreeKernelArgs * + +ostree_kernel_args_new () +
+void + +ostree_kernel_args_cleanup () +
+void + +ostree_kernel_args_replace_take () +
+void + +ostree_kernel_args_replace () +
+void + +ostree_kernel_args_replace_argv () +
+void + +ostree_kernel_args_append () +
+void + +ostree_kernel_args_append_argv () +
+void + +ostree_kernel_args_append_argv_filtered () +
+void + +ostree_kernel_args_append_if_missing () +
+gboolean + +ostree_kernel_args_new_replace () +
+gboolean + +ostree_kernel_args_delete () +
+gboolean + +ostree_kernel_args_delete_key_entry () +
+gboolean + +ostree_kernel_args_append_proc_cmdline () +
+void + +ostree_kernel_args_parse_append () +
const char * + +ostree_kernel_args_get_last_value () +
+OstreeKernelArgs * + +ostree_kernel_args_from_string () +
+char ** + +ostree_kernel_args_to_strv () +
+char * + +ostree_kernel_args_to_string () +
+gboolean + +ostree_kernel_args_contains () +
+gboolean + +ostree_kernel_args_delete_if_present () +
+
+
+

Types and Values

+
++++ + + + + +
 OstreeKernelArgs
+
+
+

Description

+
+
+

Functions

+
+

ostree_kernel_args_free ()

+
void
+ostree_kernel_args_free (OstreeKernelArgs *kargs);
+

Frees the kargs structure

+
+

Parameters

+
+++++ + + + + + +

kargs

An OstreeKernelArgs that represents kernel arguments

 
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_new ()

+
OstreeKernelArgs *
+ostree_kernel_args_new (void);
+

Initializes a new OstreeKernelArgs structure and returns it

+

[skip]

+
+

Returns

+

A newly created OstreeKernelArgs for kernel arguments.

+

[transfer full]

+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_cleanup ()

+
void
+ostree_kernel_args_cleanup (void *loc);
+

Frees the OstreeKernelArgs structure pointed by *loc

+
+

Parameters

+
+++++ + + + + + +

loc

Address of an OstreeKernelArgs pointer

 
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_replace_take ()

+
void
+ostree_kernel_args_replace_take (OstreeKernelArgs *kargs,
+                                 char *arg);
+

Finds and replaces the old key if arg + is already in the hash table, +otherwise adds arg + as new key and split_keyeq (arg) as value. +Note that when replacing old key, the old values are freed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

arg

key or key/value pair for replacement.

[transfer full]
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_replace ()

+
void
+ostree_kernel_args_replace (OstreeKernelArgs *kargs,
+                            const char *arg);
+

Finds and replaces the old key if arg + is already in the hash table, +otherwise adds arg + as new key and split_keyeq (arg) as value. +Note that when replacing old key value pair, the old values are freed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

arg

key or key/value pair for replacement

 
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_replace_argv ()

+
void
+ostree_kernel_args_replace_argv (OstreeKernelArgs *kargs,
+                                 char **argv);
+

Finds and replaces each non-null arguments of argv + in the hash table, +otherwise adds individual arg as new key and split_keyeq (arg) as value. +Note that when replacing old key value pair, the old values are freed.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

argv

an array of key or key/value pairs

 
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_append ()

+
void
+ostree_kernel_args_append (OstreeKernelArgs *kargs,
+                           const char *arg);
+

Appends arg + which is in the form of key=value pair to the hash table kargs->table +(appends to the value list if key is already in the hash table) +and appends key to kargs->order if it is not in the hash table already.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

arg

key or key/value pair to be added

 
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_append_argv ()

+
void
+ostree_kernel_args_append_argv (OstreeKernelArgs *kargs,
+                                char **argv);
+

Appends each value in argv + to the corresponding value array and +appends key to kargs->order if it is not in the hash table already.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

argv

an array of key=value argument pairs.

[array zero-terminated=1]
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_append_argv_filtered ()

+
void
+ostree_kernel_args_append_argv_filtered
+                               (OstreeKernelArgs *kargs,
+                                char **argv,
+                                char **prefixes);
+

Appends each argument that does not have one of the prefixes + as prefix to the kargs +

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

argv

an array of key=value argument pairs.

[array zero-terminated=1]

prefixes

an array of prefix strings.

[array zero-terminated=1]
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_append_if_missing ()

+
void
+ostree_kernel_args_append_if_missing (OstreeKernelArgs *kargs,
+                                      const char *arg);
+

Appends arg + which is in the form of key=value pair to the hash table kargs->table +(appends to the value list if key is not in the hash table) +and appends key to kargs->order if it is not in the hash table.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

arg

key or key/value pair to be added

 
+
+

Since: 2022.5

+
+
+
+

ostree_kernel_args_new_replace ()

+
gboolean
+ostree_kernel_args_new_replace (OstreeKernelArgs *kargs,
+                                const char *arg,
+                                GError **error);
+

This function implements the basic logic behind key/value pair +replacement. Do note that the arg need to be properly formatted

+

When replacing key with exact one value, the arg can be in +the form: +key, key=new_val, or key=old_val=new_val +The first one swaps the old_val with the key to an empty value +The second and third replace the old_val into the new_val

+

When replacing key with multiple values, the arg can only be +in the form of: +key=old_val=new_val. Unless there is a special case where +there is an empty value associated with the key, then +key=new_val will work because old_val is empty. The empty +val will be swapped with the new_val in that case

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

kargs

OstreeKernelArgs instance

 

arg

a string argument

 

error

error instance

 
+
+
+

Returns

+

TRUE on success, FALSE on failure (and in some other instances such as:

+
    +
  1. key not found in kargs +

  2. +
  3. old value not found when arg +is in the form of key=old_val=new_val

  4. +
  5. multiple old values found when arg +is in the form of key=old_val)

  6. +
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_delete ()

+
gboolean
+ostree_kernel_args_delete (OstreeKernelArgs *kargs,
+                           const char *arg,
+                           GError **error);
+

There are few scenarios being handled for deletion:

+

1: for input arg with a single key(i.e without = for split), + the key/value pair will be deleted if there is only + one value that is associated with the key

+

2: for input arg wth key/value pair, the specific key + value pair will be deleted from the pointer array + if those exist.

+

3: If the found key has only one value + associated with it, the key entry in the table will also + be removed, and the key will be removed from order table

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

arg

key or key/value pair for deletion

 

error

an GError instance

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_delete_key_entry ()

+
gboolean
+ostree_kernel_args_delete_key_entry (OstreeKernelArgs *kargs,
+                                     const char *key,
+                                     GError **error);
+

This function removes the key entry from the hashtable +as well from the order pointer array inside kargs

+

Note: since both table and order inside kernel args +are with free function, no extra free functions are +being called as they are done automatically by GLib

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

kargs

an OstreeKernelArgs instance

 

key

the key to remove

 

error

an GError instance

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_append_proc_cmdline ()

+
gboolean
+ostree_kernel_args_append_proc_cmdline
+                               (OstreeKernelArgs *kargs,
+                                GCancellable *cancellable,
+                                GError **error);
+

Appends the command line arguments in the file "/proc/cmdline" +that does not have "BOOT_IMAGE=" and "initrd=" as prefixes to the kargs +

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

cancellable

optional GCancellable object, NULL to ignore

 

error

an GError instance

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_parse_append ()

+
void
+ostree_kernel_args_parse_append (OstreeKernelArgs *kargs,
+                                 const char *options);
+

Parses options + by separating it by whitespaces and appends each argument to kargs +

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

options

a string representing command line arguments

 
+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_get_last_value ()

+
const char *
+ostree_kernel_args_get_last_value (OstreeKernelArgs *kargs,
+                                   const char *key);
+

Finds and returns the last element of value array +corresponding to the key + in kargs + hash table. Note that the application +will be terminated if the key + is found but the value array is empty

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

key

a key to look for in kargs +hash table

 
+
+
+

Returns

+

NULL if key +is not found in the kargs +hash table, +otherwise returns last element of value array corresponding to key +.

+

[nullable]

+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_from_string ()

+
OstreeKernelArgs *
+ostree_kernel_args_from_string (const char *options);
+

Initializes a new OstreeKernelArgs then parses and appends options + +to the empty OstreeKernelArgs

+

[skip]

+
+

Parameters

+
+++++ + + + + + +

options

a string representing command line arguments

 
+
+
+

Returns

+

newly allocated OstreeKernelArgs with options +appended.

+

[transfer full]

+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_to_strv ()

+
char **
+ostree_kernel_args_to_strv (OstreeKernelArgs *kargs);
+

Extracts all key value pairs in kargs + and appends to a temporary +array in forms of "key=value" or "key" if value is NULL, and returns +the temporary array with the GPtrArray wrapper freed

+
+

Parameters

+
+++++ + + + + + +

kargs

a OstreeKernelArgs instance

 
+
+
+

Returns

+

an array of "key=value" pairs or "key" if value is NULL.

+

[transfer full]

+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_to_string ()

+
char *
+ostree_kernel_args_to_string (OstreeKernelArgs *kargs);
+

Extracts all key value pairs in kargs + and appends to a temporary +GString in forms of "key=value" or "key" if value is NULL separated +by a single whitespace, and returns the temporary string with the +GString wrapper freed

+

Note: the application will be terminated if one of the values array +in kargs + is NULL

+
+

Parameters

+
+++++ + + + + + +

kargs

a OstreeKernelArgs instance

 
+
+
+

Returns

+

a string of "key=value" pairs or "key" if value is NULL, +separated by single whitespaces.

+

[transfer full]

+
+

Since: 2019.3

+
+
+
+

ostree_kernel_args_contains ()

+
gboolean
+ostree_kernel_args_contains (OstreeKernelArgs *kargs,
+                             const char *arg);
+

Search for arg + which is in the form of key=value pair at the hash table kargs->table +and returns true if finds it.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

arg

key or key/value pair to check

 
+
+
+

Returns

+

TRUE if arg +is contained in kargs +, FALSE otherwise.

+
+

Since: 2022.7

+
+
+
+

ostree_kernel_args_delete_if_present ()

+
gboolean
+ostree_kernel_args_delete_if_present (OstreeKernelArgs *kargs,
+                                      const char *arg,
+                                      GError **error);
+

Deletes arg + which is in the form of key=value pair from the hash table kargs->table.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

kargs

a OstreeKernelArgs instance

 

arg

key or key/value pair to be deleted

 

error

an GError instance

 
+
+
+

Returns

+

TRUE on success, FALSE on failure

+
+

Since: 2022.7

+
+
+
+

Types and Values

+
+

OstreeKernelArgs

+
typedef struct _OstreeKernelArgs OstreeKernelArgs;
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-ref.html b/reference/ostree-ostree-ref.html new file mode 100644 index 0000000000..90003270bf --- /dev/null +++ b/reference/ostree-ostree-ref.html @@ -0,0 +1,373 @@ + + + + +ostree-ref: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-ref

+

ostree-ref

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+OstreeCollectionRef * + +ostree_collection_ref_new () +
+OstreeCollectionRef * + +ostree_collection_ref_dup () +
+void + +ostree_collection_ref_free () +
+guint + +ostree_collection_ref_hash () +
+gboolean + +ostree_collection_ref_equal () +
+OstreeCollectionRef ** + +ostree_collection_ref_dupv () +
+void + +ostree_collection_ref_freev () +
+
+
+

Types and Values

+
++++ + + + + +
typedefOstreeCollectionRefv
+
+
+

Description

+
+
+

Functions

+
+

ostree_collection_ref_new ()

+
OstreeCollectionRef *
+ostree_collection_ref_new (const gchar *collection_id,
+                           const gchar *ref_name);
+

Create a new OstreeCollectionRef containing (collection_id +, ref_name +). If +collection_id + is NULL, this is equivalent to a plain ref name string (not a +refspec; no remote name is included), which can be used for non-P2P +operations.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

collection_id

a collection ID, or NULL for a plain ref.

[nullable]

ref_name

a ref name

 
+
+
+

Returns

+

a new OstreeCollectionRef.

+

[transfer full]

+
+

Since: 2018.6

+
+
+
+

ostree_collection_ref_dup ()

+
OstreeCollectionRef *
+ostree_collection_ref_dup (const OstreeCollectionRef *ref);
+

Create a copy of the given ref +.

+
+

Parameters

+
+++++ + + + + + +

ref

an OstreeCollectionRef.

[not nullable]
+
+
+

Returns

+

a newly allocated copy of ref +.

+

[transfer full]

+
+

Since: 2018.6

+
+
+
+

ostree_collection_ref_free ()

+
void
+ostree_collection_ref_free (OstreeCollectionRef *ref);
+

Free the given ref +.

+
+

Parameters

+
+++++ + + + + + +

ref

an OstreeCollectionRef.

[transfer full]
+
+

Since: 2018.6

+
+
+
+

ostree_collection_ref_hash ()

+
guint
+ostree_collection_ref_hash (gconstpointer ref);
+

Hash the given ref +. This function is suitable for use with GHashTable. +ref + must be non-NULL.

+
+

Parameters

+
+++++ + + + + + +

ref

an OstreeCollectionRef.

[not nullable][type OstreeCollectionRef]
+
+
+

Returns

+

hash value for ref +

+
+

Since: 2018.6

+
+
+
+

ostree_collection_ref_equal ()

+
gboolean
+ostree_collection_ref_equal (gconstpointer ref1,
+                             gconstpointer ref2);
+

Compare ref1 + and ref2 + and return TRUE if they have the same collection ID and +ref name, and FALSE otherwise. Both ref1 + and ref2 + must be non-NULL.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

ref1

an OstreeCollectionRef.

[not nullable][type OstreeCollectionRef]

ref2

another OstreeCollectionRef.

[not nullable][type OstreeCollectionRef]
+
+
+

Returns

+

TRUE if ref1 +and ref2 +are equal, FALSE otherwise

+
+

Since: 2018.6

+
+
+
+

ostree_collection_ref_dupv ()

+
OstreeCollectionRef **
+ostree_collection_ref_dupv (const OstreeCollectionRef *const *refs);
+

Copy an array of OstreeCollectionRefs, including deep copies of all its +elements. refs + must be NULL-terminated; it may be empty, but must not be +NULL.

+
+

Parameters

+
+++++ + + + + + +

refs

NULL-terminated array of OstreeCollectionRefs.

[array zero-terminated=1]
+
+
+

Returns

+

a newly allocated copy of refs +.

+

[transfer full][array zero-terminated=1]

+
+

Since: 2018.6

+
+
+
+

ostree_collection_ref_freev ()

+
void
+ostree_collection_ref_freev (OstreeCollectionRef **refs);
+

Free the given array of refs +, including freeing all its elements. refs + +must be NULL-terminated; it may be empty, but must not be NULL.

+
+

Parameters

+
+++++ + + + + + +

refs

an array of OstreeCollectionRefs.

[transfer full][array zero-terminated=1]
+
+

Since: 2018.6

+
+
+
+

Types and Values

+
+

OstreeCollectionRefv

+
typedef OstreeCollectionRef **OstreeCollectionRefv;
+
+

A NULL-terminated array of OstreeCollectionRef instances, designed to +be used with g_auto():

+
+ + + + + + + +
1
g_auto(OstreeCollectionRefv) refs = NULL;
+
+ +

+

Since: 2018.6

+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-remote.html b/reference/ostree-ostree-remote.html new file mode 100644 index 0000000000..5cfd768b5d --- /dev/null +++ b/reference/ostree-ostree-remote.html @@ -0,0 +1,230 @@ + + + + +ostree-remote: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-remote

+

ostree-remote

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + +
+OstreeRemote * + +ostree_remote_ref () +
+void + +ostree_remote_unref () +
const gchar * + +ostree_remote_get_name () +
+gchar * + +ostree_remote_get_url () +
+
+
+

Types and Values

+
++++ + + + + +
structOstreeRemote
+
+
+

Description

+
+
+

Functions

+
+

ostree_remote_ref ()

+
OstreeRemote *
+ostree_remote_ref (OstreeRemote *remote);
+

Increase the reference count on the given remote +.

+
+

Parameters

+
+++++ + + + + + +

remote

an OstreeRemote

 
+
+
+

Returns

+

a copy of remote +, for convenience.

+

[transfer full]

+
+

Since: 2018.6

+
+
+
+

ostree_remote_unref ()

+
void
+ostree_remote_unref (OstreeRemote *remote);
+

Decrease the reference count on the given remote + and free it if the +reference count reaches 0.

+
+

Parameters

+
+++++ + + + + + +

remote

an OstreeRemote.

[transfer full]
+
+

Since: 2018.6

+
+
+
+

ostree_remote_get_name ()

+
const gchar *
+ostree_remote_get_name (OstreeRemote *remote);
+

Get the human-readable name of the remote. This is what the user configured, +if the remote was explicitly configured; and will otherwise be a stable, +arbitrary, string.

+
+

Parameters

+
+++++ + + + + + +

remote

an OstreeRemote

 
+
+
+

Returns

+

remote’s name

+
+

Since: 2018.6

+
+
+
+

ostree_remote_get_url ()

+
gchar *
+ostree_remote_get_url (OstreeRemote *remote);
+

Get the URL from the remote.

+
+

Parameters

+
+++++ + + + + + +

remote

an OstreeRemote

 
+
+
+

Returns

+

the remote's URL.

+

[transfer full][nullable]

+
+

Since: 2018.6

+
+
+
+

Types and Values

+
+

struct OstreeRemote

+
struct OstreeRemote {
+  int ref_count;      /* atomic */
+  char *name;         /* (not nullable) */
+  char *refspec_name; /* (nullable) */
+  char *group;        /* group name in options (not nullable) */
+  char *keyring;      /* keyring name ($refspec_name.trustedkeys.gpg) (not nullable) */
+  GFile *file;        /* NULL if remote defined in repo/config */
+  GKeyFile *options;
+};
+
+

This represents the configuration for a single remote repository. Currently, +remotes can only be passed around as (reference counted) opaque handles. In +future, more API may be added to create and interrogate them.

+

Since: 2018.6

+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-repo-file.html b/reference/ostree-ostree-repo-file.html new file mode 100644 index 0000000000..365900fb6f --- /dev/null +++ b/reference/ostree-ostree-repo-file.html @@ -0,0 +1,512 @@ + + + + +ostree-repo-file: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-repo-file

+

ostree-repo-file

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+gboolean + +ostree_repo_file_ensure_resolved () +
+gboolean + +ostree_repo_file_get_xattrs () +
+OstreeRepo * + +ostree_repo_file_get_repo () +
+OstreeRepoFile * + +ostree_repo_file_get_root () +
+void + +ostree_repo_file_tree_set_metadata () +
const char * + +ostree_repo_file_tree_get_contents_checksum () +
const char * + +ostree_repo_file_tree_get_metadata_checksum () +
+GVariant * + +ostree_repo_file_tree_get_contents () +
+GVariant * + +ostree_repo_file_tree_get_metadata () +
const char * + +ostree_repo_file_get_checksum () +
+int + +ostree_repo_file_tree_find_child () +
+gboolean + +ostree_repo_file_tree_query_child () +
+
+
+

Types and Values

+
++++ + + + + +
typedefOstreeRepoFile
+
+
+

Description

+
+
+

Functions

+
+

ostree_repo_file_ensure_resolved ()

+
gboolean
+ostree_repo_file_ensure_resolved (OstreeRepoFile *self,
+                                  GError **error);
+

Ensure that the backing metadata is loaded.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

self

A repo file

 

error

Error

 
+
+
+

Returns

+

FALSE if the operation failed, TRUE otherwise

+
+
+
+
+

ostree_repo_file_get_xattrs ()

+
gboolean
+ostree_repo_file_get_xattrs (OstreeRepoFile *self,
+                             GVariant **out_xattrs,
+                             GCancellable *cancellable,
+                             GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

OstreeRepoFile

 

out_xattrs

the extended attributes.

[out][optional]

cancellable

Cancellable

 

error

Error

 
+
+
+
+
+

ostree_repo_file_get_repo ()

+
OstreeRepo *
+ostree_repo_file_get_repo (OstreeRepoFile *self);
+
+

Returns

+

Repository.

+

[transfer none]

+
+
+
+
+

ostree_repo_file_get_root ()

+
OstreeRepoFile *
+ostree_repo_file_get_root (OstreeRepoFile *self);
+
+

Returns

+

The root directory for the commit referenced by this file.

+

[transfer none]

+
+
+
+
+

ostree_repo_file_tree_set_metadata ()

+
void
+ostree_repo_file_tree_set_metadata (OstreeRepoFile *self,
+                                    const char *checksum,
+                                    GVariant *metadata);
+

Replace the metadata checksum and metadata object.

+
+

Parameters

+
+++++ + + + + + +

self

A repo file

 
+
+
+
+
+

ostree_repo_file_tree_get_contents_checksum ()

+
const char *
+ostree_repo_file_tree_get_contents_checksum
+                               (OstreeRepoFile *self);
+
+

Parameters

+
+++++ + + + + + +

self

A repo file

 
+
+
+

Returns

+

The SHA256 digest of the content object, or NULL if this is not a +directory.

+

[nullable]

+
+
+
+
+

ostree_repo_file_tree_get_metadata_checksum ()

+
const char *
+ostree_repo_file_tree_get_metadata_checksum
+                               (OstreeRepoFile *self);
+
+

Parameters

+
+++++ + + + + + +

self

A repo file

 
+
+
+

Returns

+

The SHA256 digest of the metadata object, or NULL if this is not a +directory.

+

[nullable]

+
+
+
+
+

ostree_repo_file_tree_get_contents ()

+
GVariant *
+ostree_repo_file_tree_get_contents (OstreeRepoFile *self);
+

This API will return NULL if the file is not "resolved" i.e. in a loaded +state. It will also return NULL if this path is not a directory tree.

+
+

Parameters

+
+++++ + + + + + +

self

A repo file

 
+
+
+

Returns

+

The GVariant representing the children of this directory.

+

[nullable]

+
+
+
+
+

ostree_repo_file_tree_get_metadata ()

+
GVariant *
+ostree_repo_file_tree_get_metadata (OstreeRepoFile *self);
+

This API will return NULL if the file is not "resolved" i.e. in a loaded +state. It will also return NULL if this path is not a directory tree.

+
+

Parameters

+
+++++ + + + + + +

self

A repo file

 
+
+
+

Returns

+

The GVariant representing the metadata for this directory.

+

[nullable]

+
+
+
+
+

ostree_repo_file_get_checksum ()

+
const char *
+ostree_repo_file_get_checksum (OstreeRepoFile *self);
+
+
+
+

ostree_repo_file_tree_find_child ()

+
int
+ostree_repo_file_tree_find_child (OstreeRepoFile *self,
+                                  const char *name,
+                                  gboolean *is_dir,
+                                  GVariant **out_container);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

OstreeRepoFile

 

name

name of the child

 

is_dir

.

[out caller-allocates]

out_container

.

[out]
+
+
+
+
+

ostree_repo_file_tree_query_child ()

+
gboolean
+ostree_repo_file_tree_query_child (OstreeRepoFile *self,
+                                   int n,
+                                   const char *attributes,
+                                   GFileQueryInfoFlags flags,
+                                   GFileInfo **out_info,
+                                   GCancellable *cancellable,
+                                   GError **error);
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

OstreeRepoFile

 

n

the child number

 

attributes

an attribute string to match, see g_file_attribute_matcher_new()

 

flags

a GFileQueryInfoFlags

 

out_info

the GFileInfo of the child.

[out][transfer full][optional]

cancellable

a GCancellable or NULL

 

error

a GError or NULL

 
+
+
+

Returns

+

TRUE on success and the out_info +is set, FALSE otherwise.

+
+
+
+
+

Types and Values

+
+

OstreeRepoFile

+
typedef struct OstreeRepoFile OstreeRepoFile;
+
+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-repo-finder.html b/reference/ostree-ostree-repo-finder.html new file mode 100644 index 0000000000..337e70bd62 --- /dev/null +++ b/reference/ostree-ostree-repo-finder.html @@ -0,0 +1,577 @@ + + + + +ostree-repo-finder: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-repo-finder

+

ostree-repo-finder

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+void + +ostree_repo_finder_resolve_async () +
+GPtrArray * + +ostree_repo_finder_resolve_finish () +
+void + +ostree_repo_finder_resolve_all_async () +
+GPtrArray * + +ostree_repo_finder_resolve_all_finish () +
+OstreeRepoFinderResult * + +ostree_repo_finder_result_new () +
+OstreeRepoFinderResult * + +ostree_repo_finder_result_dup () +
+void + +ostree_repo_finder_result_free () +
+gint + +ostree_repo_finder_result_compare () +
+void + +ostree_repo_finder_result_freev () +
+
+
+

Types and Values

+
++++ + + + + + + + + + + +
 OstreeRepoFinder
typedefOstreeRepoFinderResultv
+
+
+

Description

+
+
+

Functions

+
+

ostree_repo_finder_resolve_async ()

+
void
+ostree_repo_finder_resolve_async (OstreeRepoFinder *self,
+                                  const OstreeCollectionRef *const *refs,
+                                  OstreeRepo *parent_repo,
+                                  GCancellable *cancellable,
+                                  GAsyncReadyCallback callback,
+                                  gpointer user_data);
+

Find reachable remote URIs which claim to provide any of the given refs +. The +specific method for finding the remotes depends on the OstreeRepoFinder +implementation.

+

Any remote which is found and which claims to support any of the given refs + +will be returned in the results. It is possible that a remote claims to +support a given ref, but turns out not to — it is not possible to verify this +until ostree_repo_pull_from_remotes_async() is called.

+

The returned results will be sorted with the most useful first — this is +typically the remote which claims to provide the most refs +, at the lowest +latency.

+

Each result contains a mapping of refs + to the checksums of the commits +which the result provides. If the result provides the latest commit for a ref +across all of the results, the checksum will be set. Otherwise, if the +result provides an outdated commit, or doesn’t provide a given ref at all, +the checksum will not be set. Results which provide none of the requested +refs + may be listed with an empty refs map.

+

Pass the results to ostree_repo_pull_from_remotes_async() to pull the given +refs + from those remotes.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeRepoFinder

 

refs

non-empty array of collection–ref pairs to find remotes for.

[array zero-terminated=1]

parent_repo

the local repository which the refs are being resolved for, +which provides configuration information and GPG keys.

[transfer none]

cancellable

a GCancellable, or NULL.

[nullable]

callback

asynchronous completion callback

 

user_data

data to pass to callback +

 
+
+

Since: 2018.6

+
+
+
+

ostree_repo_finder_resolve_finish ()

+
GPtrArray *
+ostree_repo_finder_resolve_finish (OstreeRepoFinder *self,
+                                   GAsyncResult *result,
+                                   GError **error);
+

Get the results from a ostree_repo_finder_resolve_async() operation.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeRepoFinder

 

result

GAsyncResult from the callback

 

error

return location for a GError

 
+
+
+

Returns

+

array of zero +or more results.

+

[transfer full][element-type OstreeRepoFinderResult]

+
+

Since: 2018.6

+
+
+
+

ostree_repo_finder_resolve_all_async ()

+
void
+ostree_repo_finder_resolve_all_async (OstreeRepoFinder *const *finders,
+                                      const OstreeCollectionRef *const *refs,
+                                      OstreeRepo *parent_repo,
+                                      GCancellable *cancellable,
+                                      GAsyncReadyCallback callback,
+                                      gpointer user_data);
+

A version of ostree_repo_finder_resolve_async() which queries one or more +finders + in parallel and combines the results.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

finders

non-empty array of OstreeRepoFinders.

[array zero-terminated=1]

refs

non-empty array of collection–ref pairs to find remotes for.

[array zero-terminated=1]

parent_repo

the local repository which the refs are being resolved for, +which provides configuration information and GPG keys.

[transfer none]

cancellable

a GCancellable, or NULL.

[nullable]

callback

asynchronous completion callback

 

user_data

data to pass to callback +

 
+
+

Since: 2018.6

+
+
+
+

ostree_repo_finder_resolve_all_finish ()

+
GPtrArray *
+ostree_repo_finder_resolve_all_finish (GAsyncResult *result,
+                                       GError **error);
+

Get the results from a ostree_repo_finder_resolve_all_async() operation.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

result

GAsyncResult from the callback

 

error

return location for a GError

 
+
+
+

Returns

+

array of zero +or more results.

+

[transfer full][element-type OstreeRepoFinderResult]

+
+

Since: 2018.6

+
+
+
+

ostree_repo_finder_result_new ()

+
OstreeRepoFinderResult *
+ostree_repo_finder_result_new (OstreeRemote *remote,
+                               OstreeRepoFinder *finder,
+                               gint priority,
+                               GHashTable *ref_to_checksum,
+                               GHashTable *ref_to_timestamp,
+                               guint64 summary_last_modified);
+

Create a new OstreeRepoFinderResult instance. The semantics for the arguments +are as described in the OstreeRepoFinderResult documentation.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

remote

an OstreeRemote containing the transport details +for the result.

[transfer none]

finder

the OstreeRepoFinder instance which produced the +result.

[transfer none]

priority

static priority of the result, where higher numbers indicate lower +priority

 

ref_to_checksum

map of collection–ref pairs to checksums provided by this result.

[element-type OstreeCollectionRef utf8][transfer none]

ref_to_timestamp

(element-type OstreeCollectionRef guint64) (nullable) +(transfer none): map of collection–ref pairs to timestamps provided by this +result

 

summary_last_modified

Unix timestamp (seconds since the epoch, UTC) when +the summary file for the result was last modified, or 0 if this is unknown

 
+
+
+

Returns

+

a new OstreeRepoFinderResult.

+

[transfer full]

+
+

Since: 2018.6

+
+
+
+

ostree_repo_finder_result_dup ()

+
OstreeRepoFinderResult *
+ostree_repo_finder_result_dup (OstreeRepoFinderResult *result);
+

Copy an OstreeRepoFinderResult.

+
+

Parameters

+
+++++ + + + + + +

result

an OstreeRepoFinderResult to copy.

[transfer none]
+
+
+

Returns

+

a newly allocated copy of result +.

+

[transfer full]

+
+

Since: 2018.6

+
+
+
+

ostree_repo_finder_result_free ()

+
void
+ostree_repo_finder_result_free (OstreeRepoFinderResult *result);
+

Free the given result +.

+
+

Parameters

+
+++++ + + + + + +

result

an OstreeRepoFinderResult.

[transfer full]
+
+

Since: 2018.6

+
+
+
+

ostree_repo_finder_result_compare ()

+
gint
+ostree_repo_finder_result_compare (const OstreeRepoFinderResult *a,
+                                   const OstreeRepoFinderResult *b);
+

Compare two OstreeRepoFinderResult instances to work out which one is better +to pull from, and hence needs to be ordered before the other.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

a

an OstreeRepoFinderResult

 

b

an OstreeRepoFinderResult

 
+
+
+

Returns

+

<0 if a +is ordered before b +, 0 if they are ordered equally, +>0 if b +is ordered before a +

+
+

Since: 2018.6

+
+
+
+

ostree_repo_finder_result_freev ()

+
void
+ostree_repo_finder_result_freev (OstreeRepoFinderResult **results);
+

Free the given results + array, freeing each element and the container.

+
+

Parameters

+
+++++ + + + + + +

results

an OstreeRepoFinderResult.

[array zero-terminated=1][transfer full]
+
+

Since: 2018.6

+
+
+
+

Types and Values

+
+

OstreeRepoFinder

+
typedef struct _OstreeRepoFinder OstreeRepoFinder;
+
+
+
+

OstreeRepoFinderResultv

+
typedef OstreeRepoFinderResult **OstreeRepoFinderResultv;
+
+

A NULL-terminated array of OstreeRepoFinderResult instances, designed to +be used with g_auto():

+
+ + + + + + + +
1
g_auto(OstreeRepoFinderResultv) results = NULL;
+
+ +

+

Since: 2018.6

+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-repo-remote-finder.html b/reference/ostree-ostree-repo-remote-finder.html new file mode 100644 index 0000000000..74533e4752 --- /dev/null +++ b/reference/ostree-ostree-repo-remote-finder.html @@ -0,0 +1,516 @@ + + + + +ostree-repo-remote-finder: OSTree API references + + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-repo-remote-finder

+

ostree-repo-remote-finder

+
+
+

Functions

+
++++ + + + + + + + + + + + + + + + + + + + + + + +
+void + +ostree_repo_find_remotes_async () +
+OstreeRepoFinderResult ** + +ostree_repo_find_remotes_finish () +
+void + +ostree_repo_pull_from_remotes_async () +
+gboolean + +ostree_repo_pull_from_remotes_finish () +
+OstreeRemote * + +ostree_repo_resolve_keyring_for_collection () +
+
+
+

Types and Values

+
++++ + + + + + + + + + + +
#defineOSTREE_REPO_METADATA_REF
#defineOSTREE_META_KEY_DEPLOY_COLLECTION_ID
+
+
+

Description

+
+
+

Functions

+
+

ostree_repo_find_remotes_async ()

+
void
+ostree_repo_find_remotes_async (OstreeRepo *self,
+                                const OstreeCollectionRef *const *refs,
+                                GVariant *options,
+                                OstreeRepoFinder **finders,
+                                OstreeAsyncProgress *progress,
+                                GCancellable *cancellable,
+                                GAsyncReadyCallback callback,
+                                gpointer user_data);
+

Find reachable remote URIs which claim to provide any of the given named +refs +. This will search for configured remotes (OstreeRepoFinderConfig), +mounted volumes (OstreeRepoFinderMount) and (if enabled at compile time) +local network peers (OstreeRepoFinderAvahi). In order to use a custom +configuration of OstreeRepoFinder instances, call +ostree_repo_finder_resolve_all_async() on them individually.

+

Any remote which is found and which claims to support any of the given refs + +will be returned in the results. It is possible that a remote claims to +support a given ref, but turns out not to — it is not possible to verify this +until ostree_repo_pull_from_remotes_async() is called.

+

The returned results will be sorted with the most useful first — this is +typically the remote which claims to provide the most of refs +, at the lowest +latency.

+

Each result contains a list of the subset of refs + it claims to provide. It +is possible for a non-empty list of results to be returned, but for some of +refs + to not be listed in any of the results. Callers must check for this.

+

Pass the results to ostree_repo_pull_from_remotes_async() to pull the given refs + +from those remotes.

+

The following options + are currently defined:

+
    +
  • override-commit-ids (as): Array of specific commit IDs to fetch. The nth +commit ID applies to the nth ref, so this must be the same length as refs +, if +provided.

  • +
  • n-network-retries (u): Number of times to retry each download on +receiving a transient network error, such as a socket timeout; default is +5, 0 means return errors without retrying. Since: 2018.6

  • +
+

finders + must be a non-empty NULL-terminated array of the OstreeRepoFinder +instances to use, or NULL to use the system default set of finders, which +will typically be all available finders using their default options (but +this is not guaranteed).

+

GPG verification of commits will be used unconditionally.

+

This will use the thread-default GMainContext, but will not iterate it.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeRepo

 

refs

non-empty array of collection–ref pairs to find remotes for.

[array zero-terminated=1]

options

a GVariant a{sv} with an extensible set of flags.

[nullable]

finders

non-empty array of +OstreeRepoFinder instances to use, or NULL to use the system defaults.

[array zero-terminated=1][transfer none]

progress

an OstreeAsyncProgress to update with the operation’s +progress, or NULL.

[nullable]

cancellable

a GCancellable, or NULL.

[nullable]

callback

asynchronous completion callback

 

user_data

data to pass to callback +

 
+
+

Since: 2018.6

+
+
+
+

ostree_repo_find_remotes_finish ()

+
OstreeRepoFinderResult **
+ostree_repo_find_remotes_finish (OstreeRepo *self,
+                                 GAsyncResult *result,
+                                 GError **error);
+

Finish an asynchronous pull operation started with +ostree_repo_find_remotes_async().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeRepo

 

result

the asynchronous result

 

error

return location for a GError, or NULL

 
+
+
+

Returns

+

a potentially empty array +of OstreeRepoFinderResults, followed by a NULL terminator element; or +NULL on error.

+

[transfer full][array zero-terminated=1]

+
+

Since: 2018.6

+
+
+
+

ostree_repo_pull_from_remotes_async ()

+
void
+ostree_repo_pull_from_remotes_async (OstreeRepo *self,
+                                     const OstreeRepoFinderResult *const *results,
+                                     GVariant *options,
+                                     OstreeAsyncProgress *progress,
+                                     GCancellable *cancellable,
+                                     GAsyncReadyCallback callback,
+                                     gpointer user_data);
+

Pull refs from multiple remotes which have been found using +ostree_repo_find_remotes_async().

+

results + are expected to be in priority order, with the best remotes to pull +from listed first. ostree_repo_pull_from_remotes_async() will generally pull +from the remotes in order, but may parallelise its downloads.

+

If an error is encountered when pulling from a given remote, that remote will +be ignored and another will be tried instead. If any refs have not been +downloaded successfully after all remotes have been tried, G_IO_ERROR_FAILED +will be returned. The results of any successful downloads will remain cached +in the local repository.

+

If cancellable + is cancelled, G_IO_ERROR_CANCELLED will be returned +immediately. The results of any successfully completed downloads at that +point will remain cached in the local repository.

+

GPG verification of commits will be used unconditionally.

+

The following options + are currently defined:

+
    +
  • flags (i): OstreeRepoPullFlags to apply to the pull operation

  • +
  • inherit-transaction (b): TRUE to inherit an ongoing transaction on +the OstreeRepo, rather than encapsulating the pull in a new one

  • +
  • depth (i): How far in the history to traverse; default is 0, -1 means infinite

  • +
  • disable-static-deltas (b): Do not use static deltas

  • +
  • http-headers (a(ss)): Additional headers to add to all HTTP requests

  • +
  • subdirs (as): Pull just these subdirectories

  • +
  • update-frequency (u): Frequency to call the async progress callback in +milliseconds, if any; only values higher than 0 are valid

  • +
  • append-user-agent (s): Additional string to append to the user agent

  • +
  • n-network-retries (u): Number of times to retry each download on receiving +a transient network error, such as a socket timeout; default is 5, 0 +means return errors without retrying. Since: 2018.6

  • +
  • ref-keyring-map (a(sss)): Array of (collection ID, ref name, keyring +remote name) tuples specifying which remote's keyring should be used when +doing GPG verification of each collection-ref. This is useful to prevent a +remote from serving malicious updates to refs which did not originate from +it. This can be a subset or superset of the refs being pulled; any ref +not being pulled will be ignored and any ref without a keyring remote +will be verified with the keyring of the remote being pulled from.

  • +
+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeRepo

 

results

NULL-terminated array of remotes to +pull from, including the refs to pull from each.

[array zero-terminated=1]

options

A GVariant a{sv} with an extensible set of flags.

[nullable]

progress

an OstreeAsyncProgress to update with the operation’s +progress, or NULL.

[nullable]

cancellable

a GCancellable, or NULL.

[nullable]

callback

asynchronous completion callback

 

user_data

data to pass to callback +

 
+
+

Since: 2018.6

+
+
+
+

ostree_repo_pull_from_remotes_finish ()

+
gboolean
+ostree_repo_pull_from_remotes_finish (OstreeRepo *self,
+                                      GAsyncResult *result,
+                                      GError **error);
+

Finish an asynchronous pull operation started with +ostree_repo_pull_from_remotes_async().

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + +

self

an OstreeRepo

 

result

the asynchronous result

 

error

return location for a GError, or NULL

 
+
+
+

Returns

+

TRUE on success, FALSE otherwise

+
+

Since: 2018.6

+
+
+
+

ostree_repo_resolve_keyring_for_collection ()

+
OstreeRemote *
+ostree_repo_resolve_keyring_for_collection
+                               (OstreeRepo *self,
+                                const gchar *collection_id,
+                                GCancellable *cancellable,
+                                GError **error);
+

Find the GPG keyring for the given collection_id +, using the local +configuration from the given OstreeRepo. This will search the configured +remotes for ones whose collection-id key matches collection_id +, and will +return the first matching remote.

+

If multiple remotes match and have different keyrings, a debug message will +be emitted, and the first result will be returned. It is expected that the +keyrings should match.

+

If no match can be found, a G_IO_ERROR_NOT_FOUND error will be returned.

+
+

Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +

self

an OstreeRepo

 

collection_id

the collection ID to look up a keyring for

 

cancellable

a GCancellable, or NULL.

[nullable]

error

return location for a GError, or NULL

 
+
+
+

Returns

+

OstreeRemote containing the GPG keyring for +collection_id +.

+

[transfer full]

+
+

Since: 2018.6

+
+
+
+

Types and Values

+
+

OSTREE_REPO_METADATA_REF

+
#define OSTREE_REPO_METADATA_REF "ostree-metadata"
+
+

The name of a ref which is used to store metadata for the entire repository, +such as its expected update time (ostree.summary.expires), name, or new +GPG keys. Metadata is stored on contentless commits in the ref, and hence is +signed with the commits.

+

This supersedes the additional metadata dictionary in the summary file +(see ostree_repo_regenerate_summary()), as the use of a ref means that the +metadata for multiple upstream repositories can be included in a single mirror +repository, disambiguating the refs using collection IDs. In order to support +peer to peer redistribution of repository metadata, repositories must set a +collection ID (ostree_repo_set_collection_id()).

+

Users of OSTree may place arbitrary metadata in commits on this ref, but the +keys must be namespaced by product or developer. For example, +exampleos.end-of-life. The ostree. prefix is reserved.

+

Since: 2018.6

+
+
+
+

OSTREE_META_KEY_DEPLOY_COLLECTION_ID

+
#define OSTREE_META_KEY_DEPLOY_COLLECTION_ID "ostree.deploy-collection-id"
+
+

GVariant type s. This key can be used in the repo metadata which is stored +in OSTREE_REPO_METADATA_REF as well as in the summary. The semantics of this +are that the remote repository wants clients to update their remote config +to add this collection ID (clients can't do P2P operations involving a +remote without a collection ID configured on it, even if one is configured +on the server side). Clients must never change or remove a collection ID +already set in their remote config.

+

Currently, OSTree does not implement changing a remote config based on this +key, but it may do so in a later release, and until then clients such as +Flatpak may implement it.

+

This is a replacement for the similar metadata key implemented by flatpak, +xa.collection-id, which is now deprecated as clients which supported it had +bugs with their P2P implementations.

+

Since: 2018.9

+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree-ostree-version.html b/reference/ostree-ostree-version.html new file mode 100644 index 0000000000..78a663ccfa --- /dev/null +++ b/reference/ostree-ostree-version.html @@ -0,0 +1,163 @@ + + + + +ostree-version: OSTree API references + + + + + + + + + + + + + + + +
+
+
+ + +
+

ostree-version

+

ostree-version — ostree version checking

+
+
+

Functions

+
++++ + + + + +
#define +OSTREE_CHECK_VERSION() +
+
+
+

Types and Values

+
++++ + + + + + + + + + + + + + + + + + + + + + + +
#defineOSTREE_YEAR_VERSION
#defineOSTREE_RELEASE_VERSION
#defineOSTREE_VERSION
#defineOSTREE_VERSION_S
#defineOSTREE_VERSION_HEX
+
+
+

Description

+

ostree provides macros to check the version of the library +at compile-time

+
+
+

Functions

+
+

OSTREE_CHECK_VERSION()

+
#define             OSTREE_CHECK_VERSION(year,release)
+

Compile-time version checking. Evaluates to TRUE if the version +of ostree is equal or greater than the required one.

+
+

Parameters

+
+++++ + + + + + + + + + + + + +

year

required year version

 

release

required release version

 
+
+

Since: 2017.4

+
+
+
+

Types and Values

+
+

OSTREE_YEAR_VERSION

+
#define OSTREE_YEAR_VERSION (2024)
+
+

ostree year version component (e.g. 2017 if OSTREE_VERSION is 2017.2)

+

Since: 2017.4

+
+
+
+

OSTREE_RELEASE_VERSION

+
#define OSTREE_RELEASE_VERSION (6)
+
+

ostree release version component (e.g. 2 if OSTREE_VERSION is 2017.2)

+

Since: 2017.4

+
+
+
+

OSTREE_VERSION

+
#define OSTREE_VERSION (2024.6)
+
+

ostree version.

+

Since: 2017.4

+
+
+
+

OSTREE_VERSION_S

+
#define OSTREE_VERSION_S "2024.6"
+
+

ostree version, encoded as a string, useful for printing and +concatenation.

+

Since: 2017.4

+
+
+
+

OSTREE_VERSION_HEX

+
#define             OSTREE_VERSION_HEX
+

ostree version, encoded as an hexadecimal number, useful for +integer comparisons.

+

Since: 2017.4

+
+
+
+ + + \ No newline at end of file diff --git a/reference/ostree.devhelp2 b/reference/ostree.devhelp2 new file mode 100644 index 0000000000..ea7a8fe5ad --- /dev/null +++ b/reference/ostree.devhelp2 @@ -0,0 +1,679 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/reference/reference.html b/reference/reference.html new file mode 100644 index 0000000000..dc305c14fe --- /dev/null +++ b/reference/reference.html @@ -0,0 +1,2226 @@ + + + + +API Reference: OSTree API references + + + + + + + + + + + + + + + + +
+

+API Reference

+
+
+Core repository-independent functions — Create, validate, and convert core data types +
+
+OstreeRepo: Content-addressed object store — A git-like storage system for operating system binaries +
+
+In-memory modifiable filesystem tree — Modifiable filesystem tree +
+
+Root partition mount point — Manage physical root filesystem +
+
+Progress notification system for asynchronous operations — Values representing progress +
+
+SELinux policy management — Read SELinux policy and manage filesystem labels +
+
+Simple upgrade class — Upgrade OSTree systems +
+
+GPG signature verification results — Inspect detached GPG signatures +
+
+Signature management — Sign and verify commits +
+
+ostree-bootconfig-parser +
+
+ostree-chain-input-stream +
+
+ostree-checksum-input-stream +
+
+ostree-content-writer +
+
+ostree-deployment +
+
+ostree-diff +
+
+ostree-kernel-args +
+
+ostree-ref +
+
+ostree-remote +
+
+ostree-repo-file +
+
+ostree-repo-finder +
+
+ostree-repo-remote-finder +
+
+ostree-version — ostree version checking +
+
API Index
+
+
+

+API Index

+

A

+
+OstreeAsyncProgress, typedef in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_copy_state, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_finish, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_get, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_get_status, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_get_uint, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_get_uint64, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_get_variant, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_new, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_new_and_connect, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_set, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_set_status, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_set_uint, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_set_uint64, function in Progress notification system for asynchronous operations +
+
+
+ostree_async_progress_set_variant, function in Progress notification system for asynchronous operations +
+
+

B

+
+OstreeBootconfigParser, struct in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_clone, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_get, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_get_overlay_initrds, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_new, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_parse, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_parse_at, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_set, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_set_overlay_initrds, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_write, function in ostree-bootconfig-parser +
+
+
+ostree_bootconfig_parser_write_at, function in ostree-bootconfig-parser +
+
+
+ostree_break_hardlink, function in Core repository-independent functions +
+
+

C

+
+OstreeChainInputStream, struct in ostree-chain-input-stream +
+
+
+ostree_chain_input_stream_new, function in ostree-chain-input-stream +
+
+
+OstreeChecksumInputStream, struct in ostree-checksum-input-stream +
+
+
+ostree_checksum_b64_from_bytes, function in Core repository-independent functions +
+
+
+ostree_checksum_b64_inplace_from_bytes, function in Core repository-independent functions +
+
+
+ostree_checksum_b64_inplace_to_bytes, function in Core repository-independent functions +
+
+
+ostree_checksum_b64_to_bytes, function in Core repository-independent functions +
+
+
+ostree_checksum_bytes_peek, function in Core repository-independent functions +
+
+
+ostree_checksum_bytes_peek_validate, function in Core repository-independent functions +
+
+
+ostree_checksum_file, function in Core repository-independent functions +
+
+
+ostree_checksum_file_async, function in Core repository-independent functions +
+
+
+ostree_checksum_file_async_finish, function in Core repository-independent functions +
+
+
+ostree_checksum_file_at, function in Core repository-independent functions +
+
+
+ostree_checksum_file_from_input, function in Core repository-independent functions +
+
+
+ostree_checksum_from_bytes, function in Core repository-independent functions +
+
+
+ostree_checksum_from_bytes_v, function in Core repository-independent functions +
+
+
+ostree_checksum_inplace_from_bytes, function in Core repository-independent functions +
+
+
+ostree_checksum_inplace_to_bytes, function in Core repository-independent functions +
+
+
+ostree_checksum_input_stream_new, function in ostree-checksum-input-stream +
+
+
+ostree_checksum_to_bytes, function in Core repository-independent functions +
+
+
+ostree_checksum_to_bytes_v, function in Core repository-independent functions +
+
+
+OSTREE_CHECK_VERSION, macro in ostree-version +
+
+
+ostree_check_version, function in Core repository-independent functions +
+
+
+ostree_cmp_checksum_bytes, function in Core repository-independent functions +
+
+
+OstreeCollectionRefv, typedef in ostree-ref +
+
+
+ostree_collection_ref_dup, function in ostree-ref +
+
+
+ostree_collection_ref_dupv, function in ostree-ref +
+
+
+ostree_collection_ref_equal, function in ostree-ref +
+
+
+ostree_collection_ref_free, function in ostree-ref +
+
+
+ostree_collection_ref_freev, function in ostree-ref +
+
+
+ostree_collection_ref_hash, function in ostree-ref +
+
+
+ostree_collection_ref_new, function in ostree-ref +
+
+
+ostree_commit_get_content_checksum, function in Core repository-independent functions +
+
+
+ostree_commit_get_object_sizes, function in Core repository-independent functions +
+
+
+ostree_commit_get_parent, function in Core repository-independent functions +
+
+
+ostree_commit_get_timestamp, function in Core repository-independent functions +
+
+
+OSTREE_COMMIT_GVARIANT_FORMAT, macro in Core repository-independent functions +
+
+
+OSTREE_COMMIT_GVARIANT_STRING, macro in Core repository-independent functions +
+
+
+ostree_commit_metadata_for_bootable, function in Core repository-independent functions +
+
+
+ostree_commit_sizes_entry_copy, function in Core repository-independent functions +
+
+
+ostree_commit_sizes_entry_free, function in Core repository-independent functions +
+
+
+ostree_commit_sizes_entry_new, function in Core repository-independent functions +
+
+
+ostree_content_file_parse, function in Core repository-independent functions +
+
+
+ostree_content_file_parse_at, function in Core repository-independent functions +
+
+
+ostree_content_stream_parse, function in Core repository-independent functions +
+
+
+ostree_content_writer_finish, function in ostree-content-writer +
+
+
+ostree_create_directory_metadata, function in Core repository-independent functions +
+
+

D

+
+OstreeDeployment, struct in ostree-deployment +
+
+
+ostree_deployment_clone, function in ostree-deployment +
+
+
+ostree_deployment_equal, function in ostree-deployment +
+
+
+ostree_deployment_get_bootconfig, function in ostree-deployment +
+
+
+ostree_deployment_get_bootcsum, function in ostree-deployment +
+
+
+ostree_deployment_get_bootserial, function in ostree-deployment +
+
+
+ostree_deployment_get_csum, function in ostree-deployment +
+
+
+ostree_deployment_get_deployserial, function in ostree-deployment +
+
+
+ostree_deployment_get_index, function in ostree-deployment +
+
+
+ostree_deployment_get_origin, function in ostree-deployment +
+
+
+ostree_deployment_get_origin_relpath, function in ostree-deployment +
+
+
+ostree_deployment_get_osname, function in ostree-deployment +
+
+
+ostree_deployment_get_unlocked, function in ostree-deployment +
+
+
+ostree_deployment_hash, function in ostree-deployment +
+
+
+ostree_deployment_is_finalization_locked, function in ostree-deployment +
+
+
+ostree_deployment_is_pinned, function in ostree-deployment +
+
+
+ostree_deployment_is_staged, function in ostree-deployment +
+
+
+ostree_deployment_new, function in ostree-deployment +
+
+
+ostree_deployment_origin_remove_transient_state, function in ostree-deployment +
+
+
+ostree_deployment_set_bootconfig, function in ostree-deployment +
+
+
+ostree_deployment_set_bootserial, function in ostree-deployment +
+
+
+ostree_deployment_set_index, function in ostree-deployment +
+
+
+ostree_deployment_set_origin, function in ostree-deployment +
+
+
+ostree_deployment_unlocked_state_to_string, function in ostree-deployment +
+
+
+OstreeDiffFlags, enum in ostree-diff +
+
+
+OstreeDiffItem, struct in ostree-diff +
+
+
+ostree_diff_dirs, function in ostree-diff +
+
+
+ostree_diff_dirs_with_options, function in ostree-diff +
+
+
+ostree_diff_item_ref, function in ostree-diff +
+
+
+ostree_diff_item_unref, function in ostree-diff +
+
+
+ostree_diff_print, function in ostree-diff +
+
+
+OSTREE_DIRMETA_GVARIANT_FORMAT, macro in Core repository-independent functions +
+
+
+OSTREE_DIRMETA_GVARIANT_STRING, macro in Core repository-independent functions +
+
+

F

+
+OSTREE_FILEMETA_GVARIANT_FORMAT, macro in Core repository-independent functions +
+
+
+OSTREE_FILEMETA_GVARIANT_STRING, macro in Core repository-independent functions +
+
+
+ostree_fs_get_all_xattrs, function in Core repository-independent functions +
+
+
+ostree_fs_get_all_xattrs_at, function in Core repository-independent functions +
+
+

G

+
+OstreeGpgError, enum in GPG signature verification results +
+
+
+OstreeGpgSignatureAttr, enum in GPG signature verification results +
+
+
+OstreeGpgSignatureFormatFlags, enum in GPG signature verification results +
+
+
+OstreeGpgVerifyResult, typedef in GPG signature verification results +
+
+
+ostree_gpg_verify_result_count_all, function in GPG signature verification results +
+
+
+ostree_gpg_verify_result_count_valid, function in GPG signature verification results +
+
+
+ostree_gpg_verify_result_describe, function in GPG signature verification results +
+
+
+ostree_gpg_verify_result_describe_variant, function in GPG signature verification results +
+
+
+ostree_gpg_verify_result_get, function in GPG signature verification results +
+
+
+ostree_gpg_verify_result_get_all, function in GPG signature verification results +
+
+
+ostree_gpg_verify_result_lookup, function in GPG signature verification results +
+
+
+ostree_gpg_verify_result_require_valid_signature, function in GPG signature verification results +
+
+

H

+
+ostree_hash_object_name, function in Core repository-independent functions +
+
+

K

+
+OstreeKernelArgs, struct in ostree-kernel-args +
+
+
+ostree_kernel_args_append, function in ostree-kernel-args +
+
+
+ostree_kernel_args_append_argv, function in ostree-kernel-args +
+
+
+ostree_kernel_args_append_argv_filtered, function in ostree-kernel-args +
+
+
+ostree_kernel_args_append_if_missing, function in ostree-kernel-args +
+
+
+ostree_kernel_args_append_proc_cmdline, function in ostree-kernel-args +
+
+
+ostree_kernel_args_cleanup, function in ostree-kernel-args +
+
+
+ostree_kernel_args_contains, function in ostree-kernel-args +
+
+
+ostree_kernel_args_delete, function in ostree-kernel-args +
+
+
+ostree_kernel_args_delete_if_present, function in ostree-kernel-args +
+
+
+ostree_kernel_args_delete_key_entry, function in ostree-kernel-args +
+
+
+ostree_kernel_args_free, function in ostree-kernel-args +
+
+
+ostree_kernel_args_from_string, function in ostree-kernel-args +
+
+
+ostree_kernel_args_get_last_value, function in ostree-kernel-args +
+
+
+ostree_kernel_args_new, function in ostree-kernel-args +
+
+
+ostree_kernel_args_new_replace, function in ostree-kernel-args +
+
+
+ostree_kernel_args_parse_append, function in ostree-kernel-args +
+
+
+ostree_kernel_args_replace, function in ostree-kernel-args +
+
+
+ostree_kernel_args_replace_argv, function in ostree-kernel-args +
+
+
+ostree_kernel_args_replace_take, function in ostree-kernel-args +
+
+
+ostree_kernel_args_to_string, function in ostree-kernel-args +
+
+
+ostree_kernel_args_to_strv, function in ostree-kernel-args +
+
+

M

+
+OSTREE_MAX_METADATA_SIZE, macro in Core repository-independent functions +
+
+
+OSTREE_MAX_METADATA_WARN_SIZE, macro in Core repository-independent functions +
+
+
+ostree_metadata_variant_type, function in Core repository-independent functions +
+
+
+OSTREE_META_KEY_DEPLOY_COLLECTION_ID, macro in ostree-repo-remote-finder +
+
+
+OstreeMutableTree, typedef in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_check_error, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_ensure_dir, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_ensure_parent_dirs, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_fill_empty_from_dirtree, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_get_contents_checksum, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_get_files, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_get_metadata_checksum, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_get_subdirs, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_lookup, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_new, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_new_from_checksum, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_new_from_commit, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_remove, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_replace_file, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_set_contents_checksum, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_set_metadata_checksum, function in In-memory modifiable filesystem tree +
+
+
+ostree_mutable_tree_walk, function in In-memory modifiable filesystem tree +
+
+

O

+
+OstreeObjectType, enum in Core repository-independent functions +
+
+
+ostree_object_from_string, function in Core repository-independent functions +
+
+
+ostree_object_name_deserialize, function in Core repository-independent functions +
+
+
+ostree_object_name_serialize, function in Core repository-independent functions +
+
+
+ostree_object_to_string, function in Core repository-independent functions +
+
+
+ostree_object_type_from_string, function in Core repository-independent functions +
+
+
+OSTREE_OBJECT_TYPE_IS_META, macro in Core repository-independent functions +
+
+
+OSTREE_OBJECT_TYPE_LAST, macro in Core repository-independent functions +
+
+
+ostree_object_type_to_string, function in Core repository-independent functions +
+
+

P

+
+ostree_parse_refspec, function in Core repository-independent functions +
+
+

R

+
+ostree_raw_file_to_archive_z2_stream, function in Core repository-independent functions +
+
+
+ostree_raw_file_to_archive_z2_stream_with_options, function in Core repository-independent functions +
+
+
+ostree_raw_file_to_content_stream, function in Core repository-independent functions +
+
+
+OSTREE_RELEASE_VERSION, macro in ostree-version +
+
+
+OstreeRemote, struct in ostree-remote +
+
+
+ostree_remote_get_name, function in ostree-remote +
+
+
+ostree_remote_get_url, function in ostree-remote +
+
+
+ostree_remote_ref, function in ostree-remote +
+
+
+ostree_remote_unref, function in ostree-remote +
+
+
+OstreeRepo, typedef in OstreeRepo +
+
+
+OstreeRepoAutoLock, typedef in OstreeRepo +
+
+
+OstreeRepoCheckoutMode, enum in OstreeRepo +
+
+
+OstreeRepoCheckoutOverwriteMode, enum in OstreeRepo +
+
+
+OstreeRepoCommitFilter, user_function in OstreeRepo +
+
+
+OstreeRepoCommitFilterResult, enum in OstreeRepo +
+
+
+OstreeRepoCommitIterResult, enum in OstreeRepo +
+
+
+OstreeRepoCommitModifier, typedef in OstreeRepo +
+
+
+OstreeRepoCommitModifierFlags, enum in OstreeRepo +
+
+
+OstreeRepoCommitModifierXattrCallback, user_function in OstreeRepo +
+
+
+OstreeRepoCommitState, enum in OstreeRepo +
+
+
+OstreeRepoCommitTraverseFlags, enum in OstreeRepo +
+
+
+OstreeRepoFile, typedef in ostree-repo-file +
+
+
+OstreeRepoFinder, struct in ostree-repo-finder +
+
+
+OstreeRepoFinderAvahi, struct in OstreeRepoFinderAvahi +
+
+
+OstreeRepoFinderConfig, struct in OstreeRepoFinderConfig +
+
+
+OstreeRepoFinderMount, struct in OstreeRepoFinderMount +
+
+
+OstreeRepoFinderOverride, struct in OstreeRepoFinderOverride +
+
+
+OstreeRepoFinderResultv, typedef in ostree-repo-finder +
+
+
+OstreeRepoListObjectsFlags, enum in OstreeRepo +
+
+
+OstreeRepoListRefsExtFlags, enum in OstreeRepo +
+
+
+OstreeRepoLockType, enum in OstreeRepo +
+
+
+OstreeRepoMode, enum in OstreeRepo +
+
+
+OstreeRepoPruneFlags, enum in OstreeRepo +
+
+
+OstreeRepoPullFlags, enum in OstreeRepo +
+
+
+OstreeRepoRemoteChange, enum in OstreeRepo +
+
+
+OstreeRepoResolveRevExtFlags, enum in OstreeRepo +
+
+
+OstreeRepoTransactionStats, struct in OstreeRepo +
+
+
+ostree_repo_abort_transaction, function in OstreeRepo +
+
+
+ostree_repo_add_gpg_signature_summary, function in OstreeRepo +
+
+
+ostree_repo_append_gpg_signature, function in OstreeRepo +
+
+
+ostree_repo_auto_lock_cleanup, function in OstreeRepo +
+
+
+ostree_repo_auto_lock_push, function in OstreeRepo +
+
+
+ostree_repo_checkout_at, function in OstreeRepo +
+
+
+ostree_repo_checkout_at_options_set_devino, function in OstreeRepo +
+
+
+ostree_repo_checkout_gc, function in OstreeRepo +
+
+
+ostree_repo_checkout_tree, function in OstreeRepo +
+
+
+ostree_repo_checkout_tree_at, function in OstreeRepo +
+
+
+ostree_repo_commit_add_composefs_metadata, function in OstreeRepo +
+
+
+ostree_repo_commit_modifier_new, function in OstreeRepo +
+
+
+ostree_repo_commit_modifier_ref, function in OstreeRepo +
+
+
+ostree_repo_commit_modifier_set_devino_cache, function in OstreeRepo +
+
+
+ostree_repo_commit_modifier_set_sepolicy, function in OstreeRepo +
+
+
+ostree_repo_commit_modifier_set_sepolicy_from_commit, function in OstreeRepo +
+
+
+ostree_repo_commit_modifier_set_xattr_callback, function in OstreeRepo +
+
+
+ostree_repo_commit_modifier_unref, function in OstreeRepo +
+
+
+ostree_repo_commit_transaction, function in OstreeRepo +
+
+
+ostree_repo_commit_traverse_iter_cleanup, function in OstreeRepo +
+
+
+ostree_repo_commit_traverse_iter_clear, function in OstreeRepo +
+
+
+ostree_repo_commit_traverse_iter_get_dir, function in OstreeRepo +
+
+
+ostree_repo_commit_traverse_iter_get_file, function in OstreeRepo +
+
+
+ostree_repo_commit_traverse_iter_init_commit, function in OstreeRepo +
+
+
+ostree_repo_commit_traverse_iter_init_dirtree, function in OstreeRepo +
+
+
+ostree_repo_commit_traverse_iter_next, function in OstreeRepo +
+
+
+ostree_repo_copy_config, function in OstreeRepo +
+
+
+ostree_repo_create, function in OstreeRepo +
+
+
+ostree_repo_create_at, function in OstreeRepo +
+
+
+ostree_repo_delete_object, function in OstreeRepo +
+
+
+ostree_repo_devino_cache_get_type, function in OstreeRepo +
+
+
+ostree_repo_devino_cache_new, function in OstreeRepo +
+
+
+ostree_repo_devino_cache_ref, function in OstreeRepo +
+
+
+ostree_repo_devino_cache_unref, function in OstreeRepo +
+
+
+ostree_repo_equal, function in OstreeRepo +
+
+
+ostree_repo_export_tree_to_archive, function in OstreeRepo +
+
+
+ostree_repo_file_ensure_resolved, function in ostree-repo-file +
+
+
+ostree_repo_file_get_checksum, function in ostree-repo-file +
+
+
+ostree_repo_file_get_repo, function in ostree-repo-file +
+
+
+ostree_repo_file_get_root, function in ostree-repo-file +
+
+
+ostree_repo_file_get_xattrs, function in ostree-repo-file +
+
+
+ostree_repo_file_tree_find_child, function in ostree-repo-file +
+
+
+ostree_repo_file_tree_get_contents, function in ostree-repo-file +
+
+
+ostree_repo_file_tree_get_contents_checksum, function in ostree-repo-file +
+
+
+ostree_repo_file_tree_get_metadata, function in ostree-repo-file +
+
+
+ostree_repo_file_tree_get_metadata_checksum, function in ostree-repo-file +
+
+
+ostree_repo_file_tree_query_child, function in ostree-repo-file +
+
+
+ostree_repo_file_tree_set_metadata, function in ostree-repo-file +
+
+
+ostree_repo_finder_avahi_new, function in OstreeRepoFinderAvahi +
+
+
+ostree_repo_finder_avahi_start, function in OstreeRepoFinderAvahi +
+
+
+ostree_repo_finder_avahi_stop, function in OstreeRepoFinderAvahi +
+
+
+ostree_repo_finder_config_new, function in OstreeRepoFinderConfig +
+
+
+ostree_repo_finder_mount_new, function in OstreeRepoFinderMount +
+
+
+ostree_repo_finder_override_add_uri, function in OstreeRepoFinderOverride +
+
+
+ostree_repo_finder_override_new, function in OstreeRepoFinderOverride +
+
+
+ostree_repo_finder_resolve_all_async, function in ostree-repo-finder +
+
+
+ostree_repo_finder_resolve_all_finish, function in ostree-repo-finder +
+
+
+ostree_repo_finder_resolve_async, function in ostree-repo-finder +
+
+
+ostree_repo_finder_resolve_finish, function in ostree-repo-finder +
+
+
+ostree_repo_finder_result_compare, function in ostree-repo-finder +
+
+
+ostree_repo_finder_result_dup, function in ostree-repo-finder +
+
+
+ostree_repo_finder_result_free, function in ostree-repo-finder +
+
+
+ostree_repo_finder_result_freev, function in ostree-repo-finder +
+
+
+ostree_repo_finder_result_new, function in ostree-repo-finder +
+
+
+ostree_repo_find_remotes_async, function in ostree-repo-remote-finder +
+
+
+ostree_repo_find_remotes_finish, function in ostree-repo-remote-finder +
+
+
+ostree_repo_fsck_object, function in OstreeRepo +
+
+
+ostree_repo_get_bootloader, function in OstreeRepo +
+
+
+ostree_repo_get_collection_id, function in OstreeRepo +
+
+
+ostree_repo_get_config, function in OstreeRepo +
+
+
+ostree_repo_get_default_repo_finders, function in OstreeRepo +
+
+
+ostree_repo_get_dfd, function in OstreeRepo +
+
+
+ostree_repo_get_disable_fsync, function in OstreeRepo +
+
+
+ostree_repo_get_min_free_space_bytes, function in OstreeRepo +
+
+
+ostree_repo_get_mode, function in OstreeRepo +
+
+
+ostree_repo_get_parent, function in OstreeRepo +
+
+
+ostree_repo_get_path, function in OstreeRepo +
+
+
+ostree_repo_get_remote_boolean_option, function in OstreeRepo +
+
+
+ostree_repo_get_remote_list_option, function in OstreeRepo +
+
+
+ostree_repo_get_remote_option, function in OstreeRepo +
+
+
+ostree_repo_gpg_sign_data, function in OstreeRepo +
+
+
+ostree_repo_gpg_verify_data, function in OstreeRepo +
+
+
+ostree_repo_hash, function in OstreeRepo +
+
+
+ostree_repo_has_object, function in OstreeRepo +
+
+
+ostree_repo_import_archive_to_mtree, function in OstreeRepo +
+
+
+ostree_repo_import_object_from, function in OstreeRepo +
+
+
+ostree_repo_import_object_from_with_trust, function in OstreeRepo +
+
+
+ostree_repo_is_system, function in OstreeRepo +
+
+
+ostree_repo_is_writable, function in OstreeRepo +
+
+
+ostree_repo_list_collection_refs, function in OstreeRepo +
+
+
+ostree_repo_list_commit_objects_starting_with, function in OstreeRepo +
+
+
+ostree_repo_list_objects, function in OstreeRepo +
+
+
+OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE, macro in OstreeRepo +
+
+
+ostree_repo_list_refs, function in OstreeRepo +
+
+
+ostree_repo_list_refs_ext, function in OstreeRepo +
+
+
+ostree_repo_list_static_delta_indexes, function in OstreeRepo +
+
+
+ostree_repo_list_static_delta_names, function in OstreeRepo +
+
+
+ostree_repo_load_commit, function in OstreeRepo +
+
+
+ostree_repo_load_file, function in OstreeRepo +
+
+
+ostree_repo_load_object_stream, function in OstreeRepo +
+
+
+ostree_repo_load_variant, function in OstreeRepo +
+
+
+ostree_repo_load_variant_if_exists, function in OstreeRepo +
+
+
+ostree_repo_lock_pop, function in OstreeRepo +
+
+
+ostree_repo_lock_push, function in OstreeRepo +
+
+
+ostree_repo_mark_commit_partial, function in OstreeRepo +
+
+
+ostree_repo_mark_commit_partial_reason, function in OstreeRepo +
+
+
+OSTREE_REPO_METADATA_REF, macro in ostree-repo-remote-finder +
+
+
+ostree_repo_mode_from_string, function in OstreeRepo +
+
+
+ostree_repo_new, function in OstreeRepo +
+
+
+ostree_repo_new_default, function in OstreeRepo +
+
+
+ostree_repo_new_for_sysroot_path, function in OstreeRepo +
+
+
+ostree_repo_open, function in OstreeRepo +
+
+
+ostree_repo_open_at, function in OstreeRepo +
+
+
+ostree_repo_prepare_transaction, function in OstreeRepo +
+
+
+ostree_repo_prune, function in OstreeRepo +
+
+
+ostree_repo_prune_from_reachable, function in OstreeRepo +
+
+
+ostree_repo_prune_static_deltas, function in OstreeRepo +
+
+
+ostree_repo_pull, function in OstreeRepo +
+
+
+ostree_repo_pull_default_console_progress_changed, function in OstreeRepo +
+
+
+ostree_repo_pull_from_remotes_async, function in ostree-repo-remote-finder +
+
+
+ostree_repo_pull_from_remotes_finish, function in ostree-repo-remote-finder +
+
+
+ostree_repo_pull_one_dir, function in OstreeRepo +
+
+
+ostree_repo_pull_with_options, function in OstreeRepo +
+
+
+ostree_repo_query_object_storage_size, function in OstreeRepo +
+
+
+ostree_repo_read_commit, function in OstreeRepo +
+
+
+ostree_repo_read_commit_detached_metadata, function in OstreeRepo +
+
+
+ostree_repo_regenerate_metadata, function in OstreeRepo +
+
+
+ostree_repo_regenerate_summary, function in OstreeRepo +
+
+
+ostree_repo_reload_config, function in OstreeRepo +
+
+
+ostree_repo_remote_add, function in OstreeRepo +
+
+
+ostree_repo_remote_change, function in OstreeRepo +
+
+
+ostree_repo_remote_delete, function in OstreeRepo +
+
+
+ostree_repo_remote_fetch_summary, function in OstreeRepo +
+
+
+ostree_repo_remote_fetch_summary_with_options, function in OstreeRepo +
+
+
+ostree_repo_remote_get_gpg_keys, function in OstreeRepo +
+
+
+ostree_repo_remote_get_gpg_verify, function in OstreeRepo +
+
+
+ostree_repo_remote_get_gpg_verify_summary, function in OstreeRepo +
+
+
+ostree_repo_remote_get_url, function in OstreeRepo +
+
+
+ostree_repo_remote_gpg_import, function in OstreeRepo +
+
+
+ostree_repo_remote_list, function in OstreeRepo +
+
+
+ostree_repo_remote_list_collection_refs, function in OstreeRepo +
+
+
+ostree_repo_remote_list_refs, function in OstreeRepo +
+
+
+ostree_repo_resolve_collection_ref, function in OstreeRepo +
+
+
+ostree_repo_resolve_keyring_for_collection, function in ostree-repo-remote-finder +
+
+
+ostree_repo_resolve_rev, function in OstreeRepo +
+
+
+ostree_repo_resolve_rev_ext, function in OstreeRepo +
+
+
+ostree_repo_scan_hardlinks, function in OstreeRepo +
+
+
+ostree_repo_set_alias_ref_immediate, function in OstreeRepo +
+
+
+ostree_repo_set_cache_dir, function in OstreeRepo +
+
+
+ostree_repo_set_collection_id, function in OstreeRepo +
+
+
+ostree_repo_set_collection_ref_immediate, function in OstreeRepo +
+
+
+ostree_repo_set_disable_fsync, function in OstreeRepo +
+
+
+ostree_repo_set_ref_immediate, function in OstreeRepo +
+
+
+ostree_repo_signature_verify_commit_data, function in OstreeRepo +
+
+
+ostree_repo_sign_commit, function in OstreeRepo +
+
+
+ostree_repo_sign_delta, function in OstreeRepo +
+
+
+ostree_repo_static_delta_execute_offline, function in OstreeRepo +
+
+
+ostree_repo_static_delta_execute_offline_with_signature, function in OstreeRepo +
+
+
+ostree_repo_static_delta_generate, function in OstreeRepo +
+
+
+ostree_repo_static_delta_reindex, function in OstreeRepo +
+
+
+ostree_repo_static_delta_verify_signature, function in OstreeRepo +
+
+
+ostree_repo_transaction_set_collection_ref, function in OstreeRepo +
+
+
+ostree_repo_transaction_set_ref, function in OstreeRepo +
+
+
+ostree_repo_transaction_set_refspec, function in OstreeRepo +
+
+
+ostree_repo_traverse_commit, function in OstreeRepo +
+
+
+ostree_repo_traverse_commit_union, function in OstreeRepo +
+
+
+ostree_repo_traverse_commit_union_with_parents, function in OstreeRepo +
+
+
+ostree_repo_traverse_commit_with_flags, function in OstreeRepo +
+
+
+ostree_repo_traverse_new_parents, function in OstreeRepo +
+
+
+ostree_repo_traverse_new_reachable, function in OstreeRepo +
+
+
+ostree_repo_traverse_parents_get_commits, function in OstreeRepo +
+
+
+ostree_repo_traverse_reachable_refs, function in OstreeRepo +
+
+
+ostree_repo_verify_commit, function in OstreeRepo +
+
+
+ostree_repo_verify_commit_ext, function in OstreeRepo +
+
+
+ostree_repo_verify_commit_for_remote, function in OstreeRepo +
+
+
+ostree_repo_verify_summary, function in OstreeRepo +
+
+
+ostree_repo_write_archive_to_mtree, function in OstreeRepo +
+
+
+ostree_repo_write_archive_to_mtree_from_fd, function in OstreeRepo +
+
+
+ostree_repo_write_commit, function in OstreeRepo +
+
+
+ostree_repo_write_commit_detached_metadata, function in OstreeRepo +
+
+
+ostree_repo_write_commit_with_time, function in OstreeRepo +
+
+
+ostree_repo_write_config, function in OstreeRepo +
+
+
+ostree_repo_write_content, function in OstreeRepo +
+
+
+ostree_repo_write_content_async, function in OstreeRepo +
+
+
+ostree_repo_write_content_finish, function in OstreeRepo +
+
+
+ostree_repo_write_content_trusted, function in OstreeRepo +
+
+
+ostree_repo_write_dfd_to_mtree, function in OstreeRepo +
+
+
+ostree_repo_write_directory_to_mtree, function in OstreeRepo +
+
+
+ostree_repo_write_metadata, function in OstreeRepo +
+
+
+ostree_repo_write_metadata_async, function in OstreeRepo +
+
+
+ostree_repo_write_metadata_finish, function in OstreeRepo +
+
+
+ostree_repo_write_metadata_stream_trusted, function in OstreeRepo +
+
+
+ostree_repo_write_metadata_trusted, function in OstreeRepo +
+
+
+ostree_repo_write_mtree, function in OstreeRepo +
+
+
+ostree_repo_write_regfile, function in OstreeRepo +
+
+
+ostree_repo_write_regfile_inline, function in OstreeRepo +
+
+
+ostree_repo_write_symlink, function in OstreeRepo +
+
+

S

+
+OstreeSePolicy, typedef in SELinux policy management +
+
+
+OstreeSePolicyRestoreconFlags, enum in SELinux policy management +
+
+
+ostree_sepolicy_fscreatecon_cleanup, function in SELinux policy management +
+
+
+ostree_sepolicy_get_csum, function in SELinux policy management +
+
+
+ostree_sepolicy_get_label, function in SELinux policy management +
+
+
+ostree_sepolicy_get_name, function in SELinux policy management +
+
+
+ostree_sepolicy_get_path, function in SELinux policy management +
+
+
+ostree_sepolicy_new, function in SELinux policy management +
+
+
+ostree_sepolicy_new_at, function in SELinux policy management +
+
+
+ostree_sepolicy_new_from_commit, function in SELinux policy management +
+
+
+ostree_sepolicy_restorecon, function in SELinux policy management +
+
+
+ostree_sepolicy_setfscreatecon, function in SELinux policy management +
+
+
+OstreeSign, struct in Signature management +
+
+
+ostree_sign_add_pk, function in Signature management +
+
+
+ostree_sign_clear_keys, function in Signature management +
+
+
+ostree_sign_commit, function in Signature management +
+
+
+ostree_sign_commit_verify, function in Signature management +
+
+
+ostree_sign_data, function in Signature management +
+
+
+ostree_sign_data_verify, function in Signature management +
+
+
+ostree_sign_get_all, function in Signature management +
+
+
+ostree_sign_get_by_name, function in Signature management +
+
+
+ostree_sign_get_name, function in Signature management +
+
+
+ostree_sign_load_pk, function in Signature management +
+
+
+ostree_sign_metadata_format, function in Signature management +
+
+
+ostree_sign_metadata_key, function in Signature management +
+
+
+ostree_sign_set_pk, function in Signature management +
+
+
+ostree_sign_set_sk, function in Signature management +
+
+
+ostree_sign_summary, function in Signature management +
+
+
+OstreeStaticDeltaGenerateOpt, enum in OstreeRepo +
+
+
+OSTREE_SUMMARY_GVARIANT_FORMAT, macro in Core repository-independent functions +
+
+
+OSTREE_SUMMARY_GVARIANT_STRING, macro in Core repository-independent functions +
+
+
+OstreeSysroot, typedef in Root partition mount point +
+
+
+OstreeSysrootSimpleWriteDeploymentFlags, enum in Root partition mount point +
+
+
+OstreeSysrootUpgrader, typedef in Simple upgrade class +
+
+
+OstreeSysrootUpgraderFlags, enum in Simple upgrade class +
+
+
+OstreeSysrootUpgraderPullFlags, enum in Simple upgrade class +
+
+
+ostree_sysroot_change_finalization, function in Root partition mount point +
+
+
+ostree_sysroot_cleanup, function in Root partition mount point +
+
+
+ostree_sysroot_cleanup_prune_repo, function in Root partition mount point +
+
+
+ostree_sysroot_deployment_set_kargs, function in Root partition mount point +
+
+
+ostree_sysroot_deployment_set_kargs_in_place, function in Root partition mount point +
+
+
+ostree_sysroot_deployment_set_mutable, function in Root partition mount point +
+
+
+ostree_sysroot_deployment_set_pinned, function in Root partition mount point +
+
+
+ostree_sysroot_deployment_unlock, function in Root partition mount point +
+
+
+ostree_sysroot_deploy_tree, function in Root partition mount point +
+
+
+ostree_sysroot_deploy_tree_with_options, function in Root partition mount point +
+
+
+ostree_sysroot_ensure_initialized, function in Root partition mount point +
+
+
+ostree_sysroot_get_booted_deployment, function in Root partition mount point +
+
+
+ostree_sysroot_get_bootversion, function in Root partition mount point +
+
+
+ostree_sysroot_get_deployments, function in Root partition mount point +
+
+
+ostree_sysroot_get_deployment_directory, function in Root partition mount point +
+
+
+ostree_sysroot_get_deployment_dirpath, function in Root partition mount point +
+
+
+ostree_sysroot_get_deployment_origin_path, function in Root partition mount point +
+
+
+ostree_sysroot_get_fd, function in Root partition mount point +
+
+
+ostree_sysroot_get_merge_deployment, function in Root partition mount point +
+
+
+ostree_sysroot_get_path, function in Root partition mount point +
+
+
+ostree_sysroot_get_repo, function in Root partition mount point +
+
+
+ostree_sysroot_get_staged_deployment, function in Root partition mount point +
+
+
+ostree_sysroot_get_subbootversion, function in Root partition mount point +
+
+
+ostree_sysroot_initialize, function in Root partition mount point +
+
+
+ostree_sysroot_initialize_with_mount_namespace, function in Root partition mount point +
+
+
+ostree_sysroot_init_osname, function in Root partition mount point +
+
+
+ostree_sysroot_is_booted, function in Root partition mount point +
+
+
+ostree_sysroot_load, function in Root partition mount point +
+
+
+ostree_sysroot_load_if_changed, function in Root partition mount point +
+
+
+ostree_sysroot_lock, function in Root partition mount point +
+
+
+ostree_sysroot_lock_async, function in Root partition mount point +
+
+
+ostree_sysroot_lock_finish, function in Root partition mount point +
+
+
+ostree_sysroot_new, function in Root partition mount point +
+
+
+ostree_sysroot_new_default, function in Root partition mount point +
+
+
+ostree_sysroot_origin_new_from_refspec, function in Root partition mount point +
+
+
+ostree_sysroot_prepare_cleanup, function in Root partition mount point +
+
+
+ostree_sysroot_query_deployments_for, function in Root partition mount point +
+
+
+ostree_sysroot_repo, function in Root partition mount point +
+
+
+ostree_sysroot_require_booted_deployment, function in Root partition mount point +
+
+
+ostree_sysroot_set_mount_namespace_in_use, function in Root partition mount point +
+
+
+ostree_sysroot_simple_write_deployment, function in Root partition mount point +
+
+
+ostree_sysroot_stage_overlay_initrd, function in Root partition mount point +
+
+
+ostree_sysroot_stage_tree, function in Root partition mount point +
+
+
+ostree_sysroot_stage_tree_with_options, function in Root partition mount point +
+
+
+ostree_sysroot_try_lock, function in Root partition mount point +
+
+
+ostree_sysroot_unload, function in Root partition mount point +
+
+
+ostree_sysroot_unlock, function in Root partition mount point +
+
+
+ostree_sysroot_update_post_copy, function in Root partition mount point +
+
+
+ostree_sysroot_upgrader_check_timestamps, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_deploy, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_dup_origin, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_get_origin, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_get_origin_description, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_new, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_new_for_os, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_new_for_os_with_flags, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_pull, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_pull_one_dir, function in Simple upgrade class +
+
+
+ostree_sysroot_upgrader_set_origin, function in Simple upgrade class +
+
+
+ostree_sysroot_write_deployments, function in Root partition mount point +
+
+
+ostree_sysroot_write_deployments_with_options, function in Root partition mount point +
+
+
+ostree_sysroot_write_origin_file, function in Root partition mount point +
+
+

T

+
+OSTREE_TREE_GVARIANT_FORMAT, macro in Core repository-independent functions +
+
+
+OSTREE_TREE_GVARIANT_STRING, macro in Core repository-independent functions +
+
+

V

+
+ostree_validate_checksum_string, function in Core repository-independent functions +
+
+
+ostree_validate_collection_id, function in Core repository-independent functions +
+
+
+ostree_validate_remote_name, function in Core repository-independent functions +
+
+
+ostree_validate_rev, function in Core repository-independent functions +
+
+
+ostree_validate_structureof_checksum_string, function in Core repository-independent functions +
+
+
+ostree_validate_structureof_commit, function in Core repository-independent functions +
+
+
+ostree_validate_structureof_csum_v, function in Core repository-independent functions +
+
+
+ostree_validate_structureof_dirmeta, function in Core repository-independent functions +
+
+
+ostree_validate_structureof_dirtree, function in Core repository-independent functions +
+
+
+ostree_validate_structureof_file_mode, function in Core repository-independent functions +
+
+
+ostree_validate_structureof_objtype, function in Core repository-independent functions +
+
+
+OSTREE_VERSION, macro in ostree-version +
+
+
+OSTREE_VERSION_HEX, macro in ostree-version +
+
+
+OSTREE_VERSION_S, macro in ostree-version +
+
+

Y

+
+OSTREE_YEAR_VERSION, macro in ostree-version +
+
+
+
+ + + \ No newline at end of file diff --git a/reference/right-insensitive.png b/reference/right-insensitive.png new file mode 100644 index 0000000000..4c95785b90 Binary files /dev/null and b/reference/right-insensitive.png differ diff --git a/reference/right.png b/reference/right.png new file mode 100644 index 0000000000..76260ec886 Binary files /dev/null and b/reference/right.png differ diff --git a/reference/style.css b/reference/style.css new file mode 100644 index 0000000000..2eeda1f0cd --- /dev/null +++ b/reference/style.css @@ -0,0 +1,530 @@ +body +{ + font-family: cantarell, sans-serif; +} +.synopsis, .classsynopsis +{ + /* tango:aluminium 1/2 */ + background: #eeeeec; + background: rgba(238, 238, 236, 0.5); + border: solid 1px rgb(238, 238, 236); + padding: 0.5em; +} +.programlisting +{ + /* tango:sky blue 0/1 */ + /* fallback for no rgba support */ + background: #e6f3ff; + border: solid 1px #729fcf; + background: rgba(114, 159, 207, 0.1); + border: solid 1px rgba(114, 159, 207, 0.2); + padding: 0.5em; +} +.variablelist +{ + padding: 4px; + margin-left: 3em; +} +.variablelist td:first-child +{ + vertical-align: top; +} + +span.nowrap { + white-space: nowrap; +} + +div.gallery-float +{ + float: left; + padding: 10px; +} +div.gallery-float img +{ + border-style: none; +} +div.gallery-spacer +{ + clear: both; +} + +a, a:visited +{ + text-decoration: none; + /* tango:sky blue 2 */ + color: #3465a4; +} +a:hover +{ + text-decoration: underline; + /* tango:sky blue 1 */ + color: #729fcf; +} + +.function_type, +.variable_type, +.property_type, +.signal_type, +.parameter_name, +.struct_member_name, +.union_member_name, +.define_keyword, +.datatype_keyword, +.typedef_keyword +{ + text-align: right; +} + +/* dim non-primary columns */ +.c_punctuation, +.function_type, +.variable_type, +.property_type, +.signal_type, +.define_keyword, +.datatype_keyword, +.typedef_keyword, +.property_flags, +.signal_flags, +.parameter_annotations, +.enum_member_annotations, +.struct_member_annotations, +.union_member_annotations +{ + color: #888a85; +} + +.function_type a, +.function_type a:visited, +.function_type a:hover, +.property_type a, +.property_type a:visited, +.property_type a:hover, +.signal_type a, +.signal_type a:visited, +.signal_type a:hover, +.signal_flags a, +.signal_flags a:visited, +.signal_flags a:hover +{ + color: #729fcf; +} + +td p +{ + margin: 0.25em; +} + +div.informaltable table[border="1"], +div.table table +{ + border-collapse: collapse; + border-spacing: 0px; + /* tango:aluminium 3 */ + border: solid 1px #babdb6; +} + +div.informaltable table[border="1"] td, +div.informaltable table th, +div.table table td, div.table table th +{ + /* tango:aluminium 3 */ + border: solid 1px #babdb6; + padding: 3px; + vertical-align: top; +} + +div.informaltable table[border="1"] th, +div.table table th +{ + /* tango:aluminium 2 */ + background-color: #d3d7cf; +} + +h4 +{ + color: #555753; + margin-top: 1em; + margin-bottom: 1em; +} + +hr +{ + /* tango:aluminium 1 */ + color: #d3d7cf; + background: #d3d7cf; + border: none 0px; + height: 1px; + clear: both; + margin: 2.0em 0em 2.0em 0em; +} + +dl.toc dt +{ + padding-bottom: 0.25em; +} + +dl.toc > dt +{ + padding-top: 0.25em; + padding-bottom: 0.25em; + font-weight: bold; +} + +dl.toc > dl +{ + padding-bottom: 0.5em; +} + +.parameter +{ + font-style: normal; +} + +.footer +{ + padding-top: 3.5em; + /* tango:aluminium 3 */ + color: #babdb6; + text-align: center; + font-size: 80%; +} + +.informalfigure, +.figure +{ + margin: 1em; +} + +.informalexample, +.example +{ + margin-top: 1em; + margin-bottom: 1em; +} + +.warning +{ + /* tango:orange 0/1 */ + background: #ffeed9; + background: rgba(252, 175, 62, 0.1); + border-color: #ffb04f; + border-color: rgba(252, 175, 62, 0.2); +} +.note +{ + /* tango:chameleon 0/0.5 */ + background: #d8ffb2; + background: rgba(138, 226, 52, 0.1); + border-color: #abf562; + border-color: rgba(138, 226, 52, 0.2); +} +div.blockquote +{ + border-color: #eeeeec; +} +.note, .warning, div.blockquote +{ + padding: 0.5em; + border-width: 1px; + border-style: solid; + margin: 2em; +} +.note p, .warning p +{ + margin: 0; +} + +div.warning h3.title, +div.note h3.title +{ + display: none; +} + +p + div.section +{ + margin-top: 1em; +} + +div.refnamediv, +div.refsynopsisdiv, +div.refsect1, +div.refsect2, +div.toc, +div.section +{ + margin-bottom: 1em; +} + +/* blob links */ +h2 .extralinks, h3 .extralinks +{ + float: right; + /* tango:aluminium 3 */ + color: #babdb6; + font-size: 80%; + font-weight: normal; +} + +.lineart +{ + color: #d3d7cf; + font-weight: normal; +} + +.annotation +{ + /* tango:aluminium 5 */ + color: #555753; + font-weight: normal; +} + +.structfield +{ + font-style: normal; + font-weight: normal; +} + +acronym,abbr +{ + border-bottom: 1px dotted gray; +} + +.listing_frame { + /* tango:sky blue 1 */ + border: solid 1px #729fcf; + border: solid 1px rgba(114, 159, 207, 0.2); + padding: 0px; +} + +.listing_lines, .listing_code { + margin-top: 0px; + margin-bottom: 0px; + padding: 0.5em; +} +.listing_lines { + /* tango:sky blue 0.5 */ + background: #a6c5e3; + background: rgba(114, 159, 207, 0.2); + /* tango:aluminium 6 */ + color: #2e3436; +} +.listing_code { + /* tango:sky blue 0 */ + background: #e6f3ff; + background: rgba(114, 159, 207, 0.1); +} +.listing_code .programlisting { + /* override from previous */ + border: none 0px; + padding: 0px; + background: none; +} +.listing_lines pre, .listing_code pre { + margin: 0px; +} + +@media screen { + /* these have a as a first child, but since there are no parent selectors + * we can't use that. */ + a.footnote + { + position: relative; + top: 0em ! important; + } + /* this is needed so that the local anchors are displayed below the naviagtion */ + div.footnote a[name], div.refnamediv a[name], div.refsect1 a[name], div.refsect2 a[name], div.index a[name], div.glossary a[name], div.sect1 a[name] + { + display: inline-block; + position: relative; + top:-5em; + } + /* this seems to be a bug in the xsl style sheets when generating indexes */ + div.index div.index + { + top: 0em; + } + /* make space for the fixed navigation bar and add space at the bottom so that + * link targets appear somewhat close to top + */ + body + { + padding-top: 2.5em; + padding-bottom: 500px; + max-width: 60em; + } + p + { + max-width: 60em; + } + /* style and size the navigation bar */ + table.navigation#top + { + position: fixed; + background: #e2e2e2; + border-bottom: solid 1px #babdb6; + border-spacing: 5px; + margin-top: 0; + margin-bottom: 0; + top: 0; + left: 0; + z-index: 10; + } + table.navigation#top td + { + padding-left: 6px; + padding-right: 6px; + } + .navigation a, .navigation a:visited + { + /* tango:sky blue 3 */ + color: #204a87; + } + .navigation a:hover + { + /* tango:sky blue 2 */ + color: #3465a4; + } + td.shortcuts + { + /* tango:sky blue 2 */ + color: #3465a4; + font-size: 80%; + white-space: nowrap; + } + td.shortcuts .dim + { + color: #babdb6; + } + .navigation .title + { + font-size: 80%; + max-width: none; + margin: 0px; + font-weight: normal; + } +} +@media screen and (min-width: 60em) { + /* screen larger than 60em */ + body { margin: auto; } +} +@media screen and (max-width: 60em) { + /* screen less than 60em */ + #nav_hierarchy { display: none; } + #nav_interfaces { display: none; } + #nav_prerequisites { display: none; } + #nav_derived_interfaces { display: none; } + #nav_implementations { display: none; } + #nav_child_properties { display: none; } + #nav_style_properties { display: none; } + #nav_index { display: none; } + #nav_glossary { display: none; } + .gallery_image { display: none; } + .property_flags { display: none; } + .signal_flags { display: none; } + .parameter_annotations { display: none; } + .enum_member_annotations { display: none; } + .struct_member_annotations { display: none; } + .union_member_annotations { display: none; } + /* now that a column is hidden, optimize space */ + col.parameters_name { width: auto; } + col.parameters_description { width: auto; } + col.struct_members_name { width: auto; } + col.struct_members_description { width: auto; } + col.enum_members_name { width: auto; } + col.enum_members_description { width: auto; } + col.union_members_name { width: auto; } + col.union_members_description { width: auto; } + .listing_lines { display: none; } +} +@media print { + table.navigation { + visibility: collapse; + display: none; + } + div.titlepage table.navigation { + visibility: visible; + display: table; + background: #e2e2e2; + border: solid 1px #babdb6; + margin-top: 0; + margin-bottom: 0; + top: 0; + left: 0; + height: 3em; + } +} + +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.hll { background-color: #ffffcc } +.c { color: #3D7B7B; font-style: italic } /* Comment */ +.err { border: 1px solid #FF0000 } /* Error */ +.k { color: #008000; font-weight: bold } /* Keyword */ +.o { color: #666666 } /* Operator */ +.ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */ +.cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */ +.cp { color: #9C6500 } /* Comment.Preproc */ +.cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */ +.c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */ +.cs { color: #3D7B7B; font-style: italic } /* Comment.Special */ +.gd { color: #A00000 } /* Generic.Deleted */ +.ge { font-style: italic } /* Generic.Emph */ +.gr { color: #E40000 } /* Generic.Error */ +.gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.gi { color: #008400 } /* Generic.Inserted */ +.go { color: #717171 } /* Generic.Output */ +.gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.gs { font-weight: bold } /* Generic.Strong */ +.gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.gt { color: #0044DD } /* Generic.Traceback */ +.kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.kp { color: #008000 } /* Keyword.Pseudo */ +.kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.kt { color: #B00040 } /* Keyword.Type */ +.m { color: #666666 } /* Literal.Number */ +.s { color: #BA2121 } /* Literal.String */ +.na { color: #687822 } /* Name.Attribute */ +.nb { color: #008000 } /* Name.Builtin */ +.nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.no { color: #880000 } /* Name.Constant */ +.nd { color: #AA22FF } /* Name.Decorator */ +.ni { color: #717171; font-weight: bold } /* Name.Entity */ +.ne { color: #CB3F38; font-weight: bold } /* Name.Exception */ +.nf { color: #0000FF } /* Name.Function */ +.nl { color: #767600 } /* Name.Label */ +.nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.nt { color: #008000; font-weight: bold } /* Name.Tag */ +.nv { color: #19177C } /* Name.Variable */ +.ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.w { color: #bbbbbb } /* Text.Whitespace */ +.mb { color: #666666 } /* Literal.Number.Bin */ +.mf { color: #666666 } /* Literal.Number.Float */ +.mh { color: #666666 } /* Literal.Number.Hex */ +.mi { color: #666666 } /* Literal.Number.Integer */ +.mo { color: #666666 } /* Literal.Number.Oct */ +.sa { color: #BA2121 } /* Literal.String.Affix */ +.sb { color: #BA2121 } /* Literal.String.Backtick */ +.sc { color: #BA2121 } /* Literal.String.Char */ +.dl { color: #BA2121 } /* Literal.String.Delimiter */ +.sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.s2 { color: #BA2121 } /* Literal.String.Double */ +.se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */ +.sh { color: #BA2121 } /* Literal.String.Heredoc */ +.si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */ +.sx { color: #008000 } /* Literal.String.Other */ +.sr { color: #A45A77 } /* Literal.String.Regex */ +.s1 { color: #BA2121 } /* Literal.String.Single */ +.ss { color: #19177C } /* Literal.String.Symbol */ +.bp { color: #008000 } /* Name.Builtin.Pseudo */ +.fm { color: #0000FF } /* Name.Function.Magic */ +.vc { color: #19177C } /* Name.Variable.Class */ +.vg { color: #19177C } /* Name.Variable.Global */ +.vi { color: #19177C } /* Name.Variable.Instance */ +.vm { color: #19177C } /* Name.Variable.Magic */ +.il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/reference/up-insensitive.png b/reference/up-insensitive.png new file mode 100644 index 0000000000..f40498606d Binary files /dev/null and b/reference/up-insensitive.png differ diff --git a/reference/up.png b/reference/up.png new file mode 100644 index 0000000000..80b4b37e99 Binary files /dev/null and b/reference/up.png differ diff --git a/related-projects/index.html b/related-projects/index.html new file mode 100644 index 0000000000..fe89c9a9af --- /dev/null +++ b/related-projects/index.html @@ -0,0 +1,770 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Related Projects | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Related Projects + + +

+ + +
    +
  1. Combining dpkg/rpm + (BTRFS/LVM)
  2. +
  3. ChromiumOS updater
  4. +
  5. Ubuntu Image Based Updates
  6. +
  7. Clear Linux Software update
  8. +
  9. casync
  10. +
  11. Mender.io
  12. +
  13. OLPC update
  14. +
  15. NixOS / Nix
  16. +
  17. Solaris IPS
  18. +
  19. Google servers (custom rsync-like approach, live updates)
  20. +
  21. Conary
  22. +
  23. bmap
  24. +
  25. Git
  26. +
  27. Conda
  28. +
  29. rpm-ostree
  30. +
  31. GNOME Continuous
  32. +
  33. Docker
  34. +
  35. Docker-related: Balena
  36. +
  37. Torizon Platform
      +
    1. Torizon OS
    2. +
    3. TorizonCore Builder
    4. +
    5. Torizon Cloud
    6. +
    +
  38. +
+ + + +

OSTree is in many ways very evolutionary. It builds on concepts and +ideas introduced from many different projects such as +Systemd Stateless, +Systemd Bootloader Spec, +Chromium Autoupdate, +the much older +Fedora/Red Hat Stateless Project, +Linux VServer +and many more.

+ +

As mentioned elsewhere, OSTree is strongly influenced by package +manager designs as well. This page is not intended to be an +exhaustive list of such projects, but we will try to keep it up to +date, and relatively agnostic.

+ +

Broadly speaking, projects in this area fall into two camps; either +a tool to snapshot systems on the client side (dpkg/rpm + BTRFS/LVM), +or a tool to compose on a server and replicate (ChromiumOS, Clear +Linux). OSTree is flexible enough to do both.

+ +

Note that this section of the documentation is almost entirely +focused on the “ostree for host” model; the flatpak +project uses libostree to store application data, distinct from the +host system management model.

+

+ + + Combining dpkg/rpm + (BTRFS/LVM) + + +

+ + +

In this approach, one uses a block/filesystem snapshot tool underneath +the system package manager.

+ +

The +oVirt Node imgbased +tool is an example of this approach, as are a few others below.

+ +

Regarding BTRFS +in particular - the OSTree author believes that Linux storage is a +wide world, and while BTRFS is quite good, it is not everywhere now, +nor will it be in the near future. There are other recently developed +filesystems like f2fs, and Red +Hat Enterprise Linux still defaults to +XFS.

+ +

Using a snapshot tool underneath a package manager does help +significantly. In the rest of this text, we will use “BTRFS” as a +mostly generic tool for filesystem snapshots.

+ +

The obvious thing to do is layer BTRFS under dpkg/rpm, and have a +separate subvolume for /home so rollbacks don’t lose your data. See +e.g. Fedora BTRFS Rollback Feature.

+ +

More generally, if you want to use BTRFS to roll back changes made by +dpkg/rpm, you have to carefully set up the partition layout so that +the files laid out by dpkg/rpm are installed in a subvolume to +snapshot.

+ +

This problem in many ways is addressed by the changes OSTree forces, +such as putting all local state in /var (e.g. /usr/local -> +/var/usrlocal). Then one can BTRFS snapshot /usr. This gets pretty +far, except handling /etc is messy. This is something OSTree does +well.

+ +

In general, if one really tries to flesh out the BTRFS approach, a +nontrivial middle layer of code between dpkg/rpm and BTRFS (or deep +awareness of BTRFS in dpkg/rpm itself) will be required. A good +example of this is the snapper.io project.

+ +

The OSTree author believes that having total freedom at the block +storage layer is better for general purpose operating systems. For +example, the ability to choose dm-crypt per deployment is quite useful; +not every site wants to pay the performance penalty. One can choose +LVM or not, etc.

+ +

Where applicable, OSTree does take advantage of copy-on-write/reflink +features offered by the kernel for /etc. It uses the now generic +ioctl(FICLONE) and copy_file_range().

+ +

Another major distinction between the default OSTree usage and package managers +is whether updates are “online” or “offline” by default. The default OSTree +design writes updates into a new root, leaving the running system unchanged. +This means preparing updates is completely non-disruptive and safe - if the +system runs out of disk space in the middle, it’s easy to recover. However, +there is work in the rpm-ostree +project to support online updates as well.

+ +

OSTree supports using “bare-user” repositories, which do not require +root to use. Using a filesystem-level layer without root is more +difficult and would likely require a setuid helper or privileged service.

+ +

Finally, see the next portion around ChromiumOS for why a hybrid but +integrated package/image system improves on this.

+

+ + + ChromiumOS updater + + +

+ + +

Many people who look at OSTree are most interested in using +it as an updater for embedded or fixed-purpose systems, similar to use cases +from the ChromiumOS updater.

+ +

The ChromiumOS approach uses two partitions that are swapped via the +bootloader. It has a very network-efficient update protocol, using a +custom binary delta scheme between filesystem snapshots.

+ +

This model even allows for switching filesystem types in an update.

+ +

A major downside of this approach is that the OS size is doubled on +disk always. In contrast, OSTree uses plain Unix hardlinks, which +means it essentially only requires disk space proportional to the +changed files, plus some small fixed overhead.

+ +

This means with OSTree, one can easily have more than two trees +(deployments). Another example is that the system OSTree repository +could also be used for application containers.

+ +

Finally, the author of OSTree believes that what one really wants for +many cases is image replication with the ability to layer on some +additional components (e.g. packages) - a hybrid model. This is what +rpm-ostree is aiming +to support.

+

+ + + Ubuntu Image Based Updates + + +

+ + +

See https://wiki.ubuntu.com/ImageBasedUpgrades. Very architecturally +similar to ChromeOS, although more interesting is discussion for +supporting package installation on top, similar to +rpm-ostree package layering.

+

+ + + Clear Linux Software update + + +

+ + +

The +Clear Linux Software update +system is not very well documented. +This mailing list post +has some reverse-engineered design documentation.

+ +

Like OSTree static deltas, it also uses bsdiff for network efficiency.

+ +

More information will be filled in here over time. The OSTree author +believes that at the moment, the “CL updater” is not truly atomic in +the sense that because it applies updates live, there is a window +where the OS root may be inconsistent.

+

+ + + casync + + +

+ + +

The systemd casync project is +relatively new. Currently, it is more of a storage library, and doesn’t +support higher level logic for things like GPG signatures, versioning +information, etc. This is mostly the OstreeRepo layer. Moving up to +the OstreeSysroot level - things like managing the bootloader +configuration, and most importantly implementing correct merging for /etc +are missing. casync also is unaware of SELinux.

+ +

OSTree is really today a shared library, and has been for quite some time. +This has made it easy to build higher level projects such as +rpm-ostree which has quite +a bit more, such as a DBus API and other projects consume that, such as +Cockpit.

+ +

A major issue with casync today is that it doesn’t support garbage collection +on the server side. OSTree’s GC works symmetrically on the server and client +side.

+ +

Broadly speaking, casync is a twist on the dual partition approach, and +shares the general purpose disadvantages of those.

+

+ + + Mender.io + + +

+ + +

Mender.io is another implementation of the dual +partition approach.

+

+ + + OLPC update + + +

+ + +

OSTree is basically a generalization of olpc-update, except using +plain HTTP instead of rsync. OSTree has the notion of separate trees +that one can track independently or parallel install, while still +sharing storage via the hardlinked repository, whereas olpc-update +uses version numbers for a single OS.

+ +

OSTree has built-in plain old HTTP replication which can be served +from a static webserver, whereas olpc-update uses rsync (more server +load, but more efficient on the network side). The OSTree solution to +improving network bandwidth consumption is via static deltas.

+ +

See +this comment +for a comparison.

+

+ + + NixOS / Nix + + +

+ + +

See NixOS. It was a very influential project for OSTree. +NixOS and OSTree both support the idea of independent “roots” that are bootable.

+ +

In NixOS, files in a package are accessed by a path depending on the checksums +of package inputs (build dependencies) - see +Nix store. +However, OSTree uses a commit/deploy model - it isn’t tied to any particular +directory layout, and you can put whatever data you want inside an OSTree, for +example the standard FHS layout. A both positive and negative of the Nix model +is that a change in the build dependencies (e.g. being built with a newer gcc), +requires a cascading rebuild of everything. It’s good because it makes it easy +to do massive system-wide changes such as gcc upgrades, and allows installing +multiple versions of packages at once. However, a security update to e.g. glibc +forces a rebuild of everything from scratch, and so Nix is not practical at +scale. OSTree supports using a build system that just rebuilds individual +components (packages) as they change, without forcing a rebuild of their +dependencies.

+ +

Nix automatically detects runtime package dependencies by scanning content for +hashes. OSTree only supports only system-level images, and doesn’t do dependency +management. Nix can store arbitrary files, using nix-store --add, but, more +commonly, paths are added as the result of running a derivation file generated +using the Nix language. OSTree is build-system agnostic; filesystem trees are +committed using a simple C API, and this is the only way to commit files.

+ +

OSTree automatically shares the storage of identical data using hard links into +a content-addressed store. Nix can deduplicate using hard links as well, using +the auto-optimise-store option, but this is not on by default, and Nix does not +guarantee that all of its files are in the content-addressed store. OSTree +provides a git-like command line interface for browsing the content-addressed +store, while Nix does not have this functionality.

+ +

Nix used to use the immutable bit to prevent modifications to /nix/store, but +now it uses a read-only bind mount. The bind mount can be privately remounted, +allowing per-process privileged write access. OSTree uses the immutable +bit on the root of the deployment, and mounts /usr as read-only.

+ +

NixOS supports switching OS images on-the-fly, by maintaining both booted-system +and current-system roots. It is not clear how well this approach works. OSTree +currently requries a reboot to switch images.

+ +

Finally, NixOS supports installing user-specific packages from trusted +repositories without requiring root, using a trusted daemon. +Flatpak, based on OSTree, similarly has a +policykit-based system helper that allows you to authenticate via polkit to +install into the system repository.

+

+ + + Solaris IPS + + +

+ + +

See +Solaris IPS. Broadly, +this is a similar design as to a combination of BTRFS+RPM/deb. There +is a bootloader management system which combines with the snapshots. +It’s relatively well thought through - however, it is a client-side +system assembly. If one wants to image servers and replicate +reliably, that’d be a different system.

+

+ + + Google servers (custom rsync-like approach, live updates) + + +

+ + +

This paper talks about how Google was (at least at one point) managing +updates for the host systems for some servers: +Live Upgrading Thousands of Servers from an Ancient Red Hat Distribution to 10 Year Newer Debian Based One (USENIX LISA 2013)

+

+ + + Conary + + +

+ + +

See +Conary Updates and Rollbacks. If +rpm/dpkg are like CVS, Conary is closer to Subversion. It’s not bad, +but e.g. its rollback model is rather ad-hoc and not atomic. It also +is a fully client side system and doesn’t have an image-like +replication with deltas.

+

+ + + bmap + + +

+ + +

See +bmap. +A tool for optimized copying of disk images. Intended for offline use, +so not directly comparable.

+

+ + + Git + + +

+ + +

Although OSTree has been called “Git for Binaries”, and the two share the idea +of a hashed content store, the implementation details are quite different. +OSTree supports extended attributes and uses SHA256 instead of Git’s SHA1. It +“checks out” files via hardlinks, rather than copying, and thus requires the +checkout to be immutable. At the moment, OSTree commits may have at most one +parent, as opposed to Git which allows an arbitrary number. Git uses a +smart-delta protocol for updates, while OSTree uses 1 HTTP request per changed +file, or can generate static deltas.

+

+ + + Conda + + +

+ + +

Conda is an “OS-agnostic, system-level binary +package manager and ecosystem”; although most well-known for its accompanying +Python distribution anaconda, its scope has been expanding quickly. The package +format is very similar to well-known ones such as RPM. However, unlike typical +RPMs, the packages are built to be relocatable. Also, the package manager runs +natively on Windows. Conda’s main advantage is its ability to install +collections of packages into “environments” by unpacking them all to the same +directory. Conda reduces duplication across environments using hardlinks, +similar to OSTree’s sharing between deployments (although Conda uses package / +file path instead of file hash). Overall, it is quite similar to rpm-ostree in +functionality and scope.

+

+ + + rpm-ostree + + +

+ + +

This builds on top of ostree to support building RPMs into OSTree images, and +even composing RPMs on-the-fly using an overlay filesystem. It is being +developed by Fedora, Red Hat, and CentOS as part of Project Atomic.

+

+ + + GNOME Continuous + + +

+ + +

This is a service that incrementally rebuilds and tests GNOME on every commit. +The need to make and distribute snapshots for this system was the original +inspiration for ostree.

+

+ + + Docker + + +

+ + +

It makes sense to compare OSTree and Docker as far as wire formats +go. OSTree is not itself a container tool, but can be used as a +transport/storage format for container tools.

+ +

Docker has (at the time of this writing) two format versions (v1 and +v2). v1 is deprecated, so we’ll look at format version 2.

+ +

A Docker image is a series of layers, and a layer is essentially JSON +metadata plus a tarball. The tarballs capture changes between layers, +including handling deleting files in higher layers.

+ +

Because the payload format is just tar, Docker hence captures +(numeric) uid/gid and xattrs.

+ +

This “layering” model is an interesting and powerful part of Docker, +allowing different images to reference a shared base. OSTree doesn’t +implement this natively, but it’s not difficult to implement in higher +level tools. For example in +flatpak, there’s a concept of a +SDK and runtime, and it would make a lot of sense for the SDK to +depend on the runtime, to avoid clients downloading data twice (even +if it’s deduplicated on disk).

+ +

That gets to an advantage of OSTree over Docker; OSTree checksums +individual files (not tarballs), and uses this for deduplication. +Docker (natively) only shares storage via layering.

+ +

The biggest feature OSTree has over Docker though is support for +(static) deltas, and even without pre-configured static deltas, the +archive format has “natural” deltas. Particularly for a “base +operating system”, one really wants on-wire deltas. It’d likely be +possible to extend Docker with this concept.

+ +

A core challenge both share is around metadata (particularly signing) +and search/discovery (the ostree summary file doesn’t scale very +well).

+ +

One major issue Docker has is that it checksums compressed data, +and furthermore the tar format is flexible, with multiple ways to represent data, +making it hard to impossible to reassemble and verify from on-disk state. +The tarsum effort +was intended to address this, but it was not adopted in the end for v2.

+ + + +

The Balena project forks Docker and aims +to even use Docker/OCI format for the root filesystem, and adds wire deltas +using librsync. See also discussion on libostree-list.

+

+ + + Torizon Platform + + +

+ + +

Torizon is an open-source +software platform that simplifies the development and maintenance of embedded +Linux software. It is designed to be used out-of-the-box on devices requiring +high reliability, allowing you to focus on your application and not on building +and maintaining the operating system.

+

+ + + Torizon OS + + +

+ + +

The platform OS - Torizon OS - +is a minimal OS with a Docker runtime and libostree + Aktualizr. The main goal +of this system is to allow application developers to use containers, while the +maintainers of Torizon OS focus on the base system updates.

+

+ + + TorizonCore Builder + + +

+ + +

Since the Torizon OS is meant as a binary distribution, OS customization is +made easier with TorizonCore Builder, +as the tool abstracts the handling of OSTree concepts from the final users.

+

+ + + Torizon Cloud + + +

+ + +

Torizon Cloud +is a hosted OTA update system that provides OS updates to Torizon OS using +OSTree and Aktualizr.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/repo/index.html b/repo/index.html new file mode 100644 index 0000000000..7db107e754 --- /dev/null +++ b/repo/index.html @@ -0,0 +1,478 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Anatomy of an OSTree repository | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Anatomy of an OSTree repository + + +

+ + +
    +
  1. Core object types and data model
      +
    1. Commit objects
    2. +
    3. Dirtree objects
    4. +
    5. Dirmeta objects
    6. +
    7. Content objects
    8. +
    9. Xattrs objects
    10. +
    +
  2. +
  3. Repository types and locations
      +
    1. Refs
    2. +
    3. The summary file
    4. +
    +
  4. +
+ + +

+ + + Core object types and data model + + +

+ + +

OSTree is deeply inspired by git; the core layer is a userspace +content-addressed versioning filesystem. It is worth taking some time +to familiarize yourself with +Git Internals, as this +section will assume some knowledge of how git works.

+ +

Its object types are similar to git; it has commit objects and content +objects. Git has “tree” objects, whereas OSTree splits them into +“dirtree” and “dirmeta” objects. But unlike git, OSTree’s checksums +are SHA256. And most crucially, its content objects include uid, gid, +and extended attributes (but still no timestamps).

+

+ + + Commit objects + + +

+ + +

A commit object contains metadata such as a timestamp, a log +message, and most importantly, a reference to a +dirtree/dirmeta pair of checksums which describe the root +directory of the filesystem. +Also like git, each commit in OSTree can have a parent. It is +designed to store a history of your binary builds, just like git +stores a history of source control. However, OSTree also makes +it easy to delete data, under the assumption that you can +regenerate it from source code.

+

+ + + Dirtree objects + + +

+ + +

A dirtree contains a sorted array of (filename, checksum) +pairs for content objects, and a second sorted array of +(filename, dirtree checksum, dirmeta checksum), which are +subdirectories. This type of object is stored as files +ending with .dirtree in the objects directory.

+

+ + + Dirmeta objects + + +

+ + +

In git, tree objects contain the metadata such as permissions +for their children. But OSTree splits this into a separate +object to avoid duplicating extended attribute listings. +These type of objects are stored as files ending with .dirmeta +in the objects directory.

+

+ + + Content objects + + +

+ + +

Unlike the first three object types which are metadata, designed to be +mmap()ed, the content object has a separate internal header and +payload sections. The header contains uid, gid, mode, and symbolic +link target (for symlinks), as well as extended attributes. After the +header, for regular files, the content follows. These parts together +form the SHA256 hash for content objects. The content type objects in +this format exist only in archive OSTree repositories. Today the +content part is gzip’ed and the objects are stored as files ending +with .filez in the objects directory. Because the SHA256 hash is +formed over the uncompressed content, these files do not match the +hash they are named as.

+ +

The OSTree data format intentionally does not contain timestamps. The reasoning +is that data files may be downloaded at different times, and by different build +systems, and so will have different timestamps but identical physical content. +These files may be large, so most users would like them to be shared, both in +the repository and between the repository and deployments.

+ +

This could cause problems with programs that check if files are out-of-date by +comparing timestamps. For Git, the logical choice is to not mess with +timestamps, because unnecessary rebuilding is better than a broken tree. +However, OSTree has to hardlink files to check them out, and commits are assumed +to be internally consistent with no build steps needed. For this reason, OSTree +acts as though all timestamps are set to time_t 0, so that comparisons will be +considered up-to-date. Note that for a few releases, OSTree used 1 to fix +warnings such as GNU Tar emitting “implausibly old time stamp” with 0; however, +until we have a mechanism to transition cleanly to 1, for compatibilty OSTree +is reverted to use zero again.

+

+ + + Xattrs objects + + +

+ + +

In some repository modes (e.g. bare-split-xattrs), xattrs are stored on the +side of the content objects they refer to. This is done via two dedicated +object types, file-xattrs and file-xattrs-link.

+ +

file-xattrs store xattrs data, encoded as GVariant. Each object is keyed by +the checksum of the xattrs content, allowing for multiple references.

+ +

file-xattrs-link are hardlinks which are associated to file objects. +Each object is keyed by the same checksum of the corresponding file +object. The target of the hardlink is an existing file-xattrs object. +In case of reaching the limit of too many links, this object could be +a plain file too.

+

+ + + Repository types and locations + + +

+ + +

Also unlike git, an OSTree repository can be in one of five separate +modes: bare, bare-split-xattrs, bare-user, bare-user-only, and +archive.

+ +

A bare repository is one where content files are just stored as regular +files; it’s designed to be the source of a “hardlink farm”, where each +operating system checkout is merely links into it. If you want to store files +owned by e.g. root in this mode, you must run OSTree as root.

+ +

The bare-split-xattrs mode is similar to the above one, but it does store +xattrs as separate objects. This is meant to avoid conflicts with +kernel-enforced constraints (e.g. on SELinux labels) and with other softwares +that may perform ephemeral changes to xattrs (e.g. container runtimes).

+ +

The bare-user mode is a later addition that is like bare in that +files are unpacked, but it can (and should generally) be created as +non-root. In this mode, extended metadata such as owner uid, gid, and +extended attributes are stored in extended attributes under the name +user.ostreemeta but not actually applied. +The bare-user mode is useful for build systems that run as non-root +but want to generate root-owned content, as well as non-root container +systems.

+ +

The bare-user-only mode is a variant to the bare-user mode. Unlike +bare-user, neither ownership nor extended attributes are stored. These repos +are meant to to be checked out in user mode (with the -U flag), where this +information is not applied anyway. Hence this mode may lose metadata. +The main advantage of bare-user-only is that repos can be stored on +filesystems which do not support extended attributes, such as tmpfs.

+ +

In contrast, the archive mode is designed for serving via plain +HTTP. Like tar files, it can be read/written by non-root users.

+ +

On an OSTree-deployed system, the “system repository” is /ostree/repo. It can +be read by any uid, but only written by root. The ostree command will by +default operate on the system repository; you may provide the --repo argument +to override this, or set the $OSTREE_REPO environment variable.

+

+ + + Refs + + +

+ + +

Like git, OSTree uses the terminology “references” (abbreviated +“refs”) which are text files that name (refer to) particular +commits. See the +Git Documentation +for information on how git uses them. Unlike git though, it doesn’t +usually make sense to have a “main” branch. There is a convention +for references in OSTree that looks like this: +exampleos/buildmain/x86_64-runtime and +exampleos/buildmain/x86_64-devel-debug. These two refs point to +two different generated filesystem trees. In this example, the +“runtime” tree contains just enough to run a basic system, and +“devel-debug” contains all of the developer tools and debuginfo.

+ +

The ostree supports a simple syntax using the caret ^ to refer to +the parent of a given commit. For example, +exampleos/buildmain/x86_64-runtime^ refers to the previous build, +and exampleos/buildmain/x86_64-runtime^^ refers to the one before +that.

+

+ + + The summary file + + +

+ + +

A later addition to OSTree is the concept of a “summary” file, created +via the ostree summary -u command. This was introduced for a few +reasons. A primary use case is to be compatible with +Metalink, which requires a +single file with a known checksum as a target.

+ +

The summary file primarily contains two mappings:

+ +
    +
  • A mapping of the refs and their checksums, equivalent to fetching +the ref file individually
  • +
  • A list of all static deltas, along with their metadata checksums
  • +
+ +

This currently means that it grows linearly with both items. On the +other hand, using the summary file, a client can enumerate branches.

+ +

Further, fetching the summary file over e.g. pinned TLS creates a strong +end-to-end verification of the commit or static delta.

+ +

The summary file can also be GPG signed (detached). This is currently +the only way to provide GPG signatures (transitively) on deltas.

+ +

If a repository administrator creates a summary file, they must +thereafter run ostree summary -u to update it whenever a ref is +updated or a static delta is generated.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/repository-management/index.html b/repository-management/index.html new file mode 100644 index 0000000000..f016fd7814 --- /dev/null +++ b/repository-management/index.html @@ -0,0 +1,533 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +Managing content in OSTree repositories | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + Managing content in OSTree repositories + + +

+ + +
    +
  1. Mirroring repositories
  2. +
  3. Separate development vs release repositories
  4. +
  5. Promoting content along OSTree branches - “buildmain”, “smoketested”
  6. +
  7. Promoting content between OSTree repositories
  8. +
  9. Derived data - static deltas and the summary file
  10. +
  11. Pruning our build and dev repositories
  12. +
  13. Generating “scratch” deltas for efficient initial downloads
  14. +
+ + + +

Once you have a build system going, if you actually want client +systems to retrieve the content, you will quickly feel a need for +“repository management”.

+ +

The command line tool ostree does cover some core functionality, but +doesn’t include very high level workflows. One reason is that how +content is delivered and managed has concerns very specific to the +organization. For example, some operating system content vendors may +want integration with a specific errata notification system when +generating commits.

+ +

In this section, we will describe some high level ideas and methods +for managing content in OSTree repositories, mostly independent of any +particular model or tool. That said, there is an associated upstream +project ostree-releng-scripts +which has some scripts that are intended to implement portions of +this document.

+ +

Another example of software which can assist in managing OSTree +repositories today is the Pulp Project, +which has a +Pulp OSTree plugin.

+

+ + + Mirroring repositories + + +

+ + +

It’s very common to want to perform a full or partial mirror, in +particular across organizational boundaries (e.g. an upstream OS +provider, and a user that wants offline and faster access to the +content). OSTree supports both full and partial mirroring of the base +archive content, although not yet of static deltas.

+ +

To create a mirror, first create an archive repository (you don’t +need to run this as root), then add the upstream as a remote, then use +pull --mirror.

+ +
ostree --repo=repo init --mode=archive
+ostree --repo=repo remote add exampleos https://exampleos.com/ostree/repo
+ostree --repo=repo pull --mirror exampleos:exampleos/x86_64/standard
+
+ +

You can use the --depth=-1 option to retrieve all history, or a +positive integer like 3 to retrieve just the last 3 commits.

+ +

See also the rsync-repos script in +ostree-releng-scripts.

+

+ + + Separate development vs release repositories + + +

+ + +

By default, OSTree accumulates server side history. This is actually +optional in that your build system can (using the API) write a commit +with no parent. But first, we’ll investigate the ramifications of +server side history.

+ +

Many content vendors will want to separate their internal development +with what is made public to the world. Therefore, you will want (at +least) two OSTree repositories, we’ll call them “dev” and “prod”.

+ +

To phrase this another way, let’s say you have a continuous delivery +system which is building from git and committing into your “dev” +OSTree repository. This might happen tens to hundreds of times per +day. That’s a substantial amount of history over time, and it’s +unlikely most of your content consumers (i.e. not developers/testers) +will be interested in all of it.

+ +

The original vision of OSTree was to fulfill this “dev” role, and in +particular the “archive” format was designed for it.

+ +

Then, what you’ll want to do is promote content from “dev” to “prod”. +We’ll discuss this later, but first, let’s talk about promotion +inside our “dev” repository.

+

+ + + Promoting content along OSTree branches - “buildmain”, “smoketested” + + +

+ + +

Besides multiple repositories, OSTree also supports multiple branches +inside one repository, equivalent to git’s branches. We saw in an +earlier section an example branch name like +exampleos/x86_64/standard. Choosing the branch name for your “prod” +repository is absolutely critical as client systems will reference it. +It becomes an important part of your face to the world, in the same +way the “main” branch in a git repository is.

+ +

But with your “dev” repository internally, it can be very useful to +use OSTree’s branching concepts to represent different stages in a +software delivery pipeline.

+ +

Deriving from exampleos/x86_64/standard, let’s say our “dev” +repository contains exampleos/x86_64/buildmain/standard. We choose the +term “buildmain” to represent something that came straight from git +main. It may not be tested very much.

+ +

Our next step should be to hook up a testing system (Jenkins, +Buildbot, etc.) to this. When a build (commit) passes some tests, we +want to “promote” that commit. Let’s create a new branch called +smoketested to say that some basic sanity checks pass on the +complete system. This might be where human testers get involved, for +example.

+ +

This is a basic way to “promote” the buildmain commit that passed testing:

+ +
ostree commit -b exampleos/x86_64/smoketested/standard -s 'Passed tests' --tree=ref=aec070645fe53...
+
+ +

Here we’re generating a new commit object (perhaps include in the commit +log links to build logs, etc.), but we’re reusing the content from the buildmain +commit aec070645fe53 that passed the smoketests.

+ +

For a more sophisticated implementation of this model, see the +do-release-tags +script, which includes support for things like propagating version +numbers across commit promotion.

+ +

We can easily generalize this model to have an arbitrary number of +stages like exampleos/x86_64/stage-1-pass/standard, +exampleos/x86_64/stage-2-pass/standard, etc. depending on business +requirements and logic.

+ +

In this suggested model, the “stages” are increasingly expensive. The +logic is that we don’t want to spend substantial time on e.g. network +performance tests if something basic like a systemd unit file fails on +bootup.

+

+ + + Promoting content between OSTree repositories + + +

+ + +

Now, we have our internal continuous delivery stream flowing, it’s +being tested and works. We want to periodically take the latest +commit on exampleos/x86_64/stage-3-pass/standard and expose it in +our “prod” repository as exampleos/x86_64/standard, with a much +smaller history.

+ +

We’ll have other business requirements such as writing release notes +(and potentially putting them in the OSTree commit message), etc.

+ +

In Build Systems we saw how the +pull-local command can be used to migrate content from the “build” +repository (in bare-user mode) into an archive repository for +serving to client systems.

+ +

Following this section, we now have three repositories, let’s call +them repo-build, repo-dev, and repo-prod. We’ve been pulling +content from repo-build into repo-dev (which involves gzip +compression among other things since it is a format change).

+ +

When using pull-local to migrate content between two archive +repositories, the binary content is taken unmodified. Let’s go ahead +and generate a new commit in our prod repository:

+ +
checksum=$(ostree --repo=repo-dev rev-parse exampleos/x86_64/stage-3-pass/standard`)
+ostree --repo=repo-prod pull-local repo-dev ${checksum}
+ostree --repo=repo-prod commit -b exampleos/x86_64/standard \
+       -s 'Release 1.2.3' --add-metadata-string=version=1.2.3 \
+	   --tree=ref=${checksum}
+
+ +

There are a few things going on here. First, we found the latest +commit checksum for the “stage-3 dev”, and told pull-local to copy +it, without using the branch name. We do this because we don’t want +to expose the exampleos/x86_64/stage-3-pass/standard branch name in +our “prod” repository.

+ +

Next, we generate a new commit in prod that’s referencing the exact +binary content in dev. If the “dev” and “prod” repositories are on +the same Unix filesystem, (like git) OSTree will make use of hard +links to avoid copying any content at all - making the process very +fast.

+ +

Another interesting thing to notice here is that we’re adding an +version metadata string to the commit. This is an optional +piece of metadata, but we are encouraging its use in the OSTree +ecosystem of tools. Commands like ostree admin status show it by +default.

+

+ + + Derived data - static deltas and the summary file + + +

+ + +

As discussed in Formats, the archive repository we +use for “prod” requires one HTTP fetch per client request by default. +If we’re only performing a release e.g. once a week, it’s appropriate +to use “static deltas” to speed up client updates.

+ +

So once we’ve used the above command to pull content from repo-dev +into repo-prod, let’s generate a delta against the previous commit:

+ +
ostree --repo=repo-prod static-delta generate exampleos/x86_64/standard
+
+ +

We may also want to support client systems upgrading from two +commits previous.

+ +
ostree --repo=repo-prod static-delta generate --from=exampleos/x86_64/standard^^ --to=exampleos/x86_64/standard
+
+ +

Generating a full permutation of deltas across all prior versions can +get expensive, and there is some support in the OSTree core for static +deltas which “recurse” to a parent. This can help create a model +where clients download a chain of deltas. Support for this is not +fully implemented yet however.

+ +

Regardless of whether or not you choose to generate static deltas, +you should update the summary file:

+ +
ostree --repo=repo-prod summary -u
+
+ +

(Remember, the summary command cannot be run concurrently, so this + should be triggered serially by other jobs).

+ +

There is some more information on the design of the summary file in +Repo.

+

+ + + Pruning our build and dev repositories + + +

+ + +

First, the OSTree author believes you should not use OSTree as a +“primary content store”. The binaries in an OSTree repository should +be derived from a git repository. Your build system should record +proper metadata such as the configuration options used to generate the +build, and you should be able to rebuild it if necessary. Art assets +should be stored in a system that’s designed for that +(e.g. Git LFS).

+ +

Another way to say this is that five years down the line, we are +unlikely to care about retaining the exact binaries from an OS build +on Wednesday afternoon three years ago.

+ +

We want to save space and prune our “dev” repository.

+ +
ostree --repo=repo-dev prune --refs-only --keep-younger-than="6 months ago"
+
+ +

That will truncate the history older than 6 months. Deleted commits +will have “tombstone markers” added so that you know they were +explicitly deleted, but all content in them (that is not referenced by +a still retained commit) will be garbage collected.

+

+ + + Generating “scratch” deltas for efficient initial downloads + + +

+ + +

In general, the happy path for OSTree downloads is via static deltas. +If you are in a situation where you want to download an OSTree +commit from an uninitialized repo (or one with unrelated history), you +can generate “scratch” (aka --empty deltas) which bundle all +objects for that commit.

+ +

The tradeoff here is increasing server disk space in return +for many fewer client HTTP requests.

+ +

For example:

+ +
$ ostree --repo=/path/to/repo static-delta generate --empty --to=exampleos/x86_64/testing-devel
+$ ostree --repo=/path/to/repo summary -u
+
+ +

After that, clients fetching that commit will prefer fetching the “scratch” delta if they don’t have the original ref.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + + diff --git a/var/index.html b/var/index.html new file mode 100644 index 0000000000..e4a43dcb9c --- /dev/null +++ b/var/index.html @@ -0,0 +1,383 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +OSTree and /var handling | ostreedev/ostree + + + + + + + + + + + + + + + + + + + + + Skip to main content + + + Link + + + + + + + Menu + + + + + + + Expand + + + + + + + + (external link) + + + + + + Document + + + + + + + Search + + + + + + + + + + Copy + + + + + + + Copied + + + + + + + + + + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ +

+ + + OSTree and /var handling + + +

+ + +
    +
  1. OSTree and /var handling
      +
    1. Default commit/image /var handling
    2. +
    3. Pitfalls
    4. +
    5. Examples
        +
      1. debs/RPMs which drop files into /opt (i.e. /var/opt)
      2. +
      3. Apache default content in /var/www/html
      4. +
      5. User home directories and databases
      6. +
      7. /var/lib/containers
      8. +
      9. dnf /var/lib/dnf/history.sqlite
      10. +
      +
    6. +
    7. Previous ostree /var and tmpfiles.d /usr/share/factory/var
    8. +
    +
  2. +
+ + +

+ + + Default commit/image /var handling + + +

+ + +

As of OSTree 2024.3, when a commit is “deployed” (queued to boot), +the initial content of /var in a commit will be placed into the +“stateroot” (default var) if the stateroot var is empty.

+ +

The semantics of this are intended to match that of Docker “volumes”; +consider that ostree systems have the equivalent of +VOLUME /var +by default.

+ +

It is still strongly recommended to use systemd tmpfiles.d snippets +to populate directory structure and the like in /var on firstboot, +because this is more resilent.

+ +

Even better, use StateDirectory= for systemd units.

+

+ + + Pitfalls + + +

+ + +

On subsequent upgrades, normally /var would not be empty anymore +(as it’s typically expected that basics like /var/tmp etc. are created, + if not also other local state such as /var/log etc.). Hence, +no updates from the commit/container will be applied.

+ +

To be clear then:

+ +
    +
  • Any files which already exist will not be updated.
  • +
  • Any files which are deleted in the new version will not be deleted on existing systems.
  • +
+

+ + + Examples + + +

+ +

+ + + debs/RPMs which drop files into /opt (i.e. /var/opt) + + +

+ + +

The default OSTree “strict” layout has /opt be a symlink to /var/opt. +Including any packaged content that “straddles” /usr and /var (i.e. /var/opt) +will over time cause drift because changes in the package will not be reflected on disk.

+ +

For situations like this, it’s strongly recommended to enable either +composefs.enabled = true or the root.transient = true option for ostree-prepare-root.conf +and change ensure your commit/container image has /opt as a plain directory. In the former case, +content in /opt will be immutable at runtime, the same as everything else in /usr. +In the latter case content it will be writable but transient.

+ +

There’s also a currently-experimental ../man/ostree-state-overlay@.service.xml +which can manage stateful writable overlays for individual mounts.

+

+ + + Apache default content in /var/www/html + + +

+ + +

In general, such static content would much better live in /usr - or even better, in an application container.

+

+ + + User home directories and databases + + +

+ + +

The semantics here are likely OK for the use case of “default users”.

+

+ + + /var/lib/containers + + +

+ + +

Pulling container images into OSTree commits like this would be a bad idea; similar problems as RPM content.

+

+ + + dnf /var/lib/dnf/history.sqlite + + +

+ + +

For $reasons dnf has its own database for state distinct from the RPM database, which on rpm-ostree systems is in /usr/share/rpm (under the read-only bind mount, managed by OS updates).

+ +

In an image/container-oriented flow, we don’t really care about this database which mainly holds things like “was this package user installed”. This data could move to /usr.

+

+ + + Previous ostree /var and tmpfiles.d /usr/share/factory/var + + +

+ + +

From OSTree versions 2023.8 to v2024.3 the /usr/lib/tmpfiles.d/ostree-tmpfiles.conf file included this snippet:

+ +
# Automatically propagate all /var content from /usr/share/factory/var;
+# the ostree-container stack is being changed to do this, and we want to
+# encourage ostree use cases in general to follow this pattern.
+C+! /var - - - - -
+
+ +

Until version 0.13.2 of the ostree-ext project, content in /var in fetched container images is moved to /usr/share/factory/var, but this no longer happens when targeting ostree v2024.3.

+ +

Together, this will have the semantic that on OS updates, on the next boot (early in boot), any new files/directories will be copied. For more information on this, see man tmpfiles.d.

+ +

This has been reverted, and the semantics defer to the above ostree semantic.

+ + + + + + + +
+ + + + +
+
+ + + +
+ + +
+ + + + +