1RPM-OSTREE(1) rpm-ostree RPM-OSTREE(1)
2
6 rpm-ostree - Hybrid image/package system for host operating system
7 updates
8
10 rpm-ostree {COMMAND} [OPTIONS...]
11
13 rpm-ostree is a hybrid image and package system; as the name suggests,
14 it uses OSTree for the image side, and RPM for the package side. It
15 supports composing RPMs server-side into an OSTree commit (like an
16 image), and clients can replicate that bit-for-bit, with fast
17 incremental updates. Additionally, the hybrid nature comes to the fore
18 with client-side package layering and overrides.
19 On an rpm-ostree managed system, the traditional yum (if installed) and
21 rpm tools operate in a read-only state; the RPM database is stored in
22 /usr/share/rpm which is underneath a read-only bind mount.
23 Instead of live package-by-package upgrades, the underlying OSTree
25 layer replicates a complete filesystem tree from a compose server into
26 a new deployment, available on the next reboot. One benefit of this is
27 that there will always be a previous deployment, available for
28 rollback. This also makes it easier to reliably "queue" an update
29 without destabilizing the running system at all. (Currently though
30 there's an experimental livefs command that supports changing the
31 running filesystem).
32 Note in this "pure replication" model, there is no per-client packaging
34 overhead. Dependency resolution, SELinux labeling, all of the scripts
35 etc. were run on the server side and captured in the OSTree commit.
36
38 cancel
39 Cancel a pending transaction. Exits successfully and does nothing
40 if no transaction is running. Note that it is fully safe to cancel
41 transactions such as upgrade in general.
42 db
44 Gives information pertaining to rpm data within the file system
45 trees within the ostree commits. There are three sub-commands:
46 diff to see how the packages are different between the trees in two
48 revs. If no revs are provided, the booted commit is compared to the
49 pending commit. If only a single rev is provided, the booted commit
50 is compared to that rev. The --format=diff option uses - for
51 removed packages, + for added packages, and finally ! for the old
52 version of an updated package, with a following = for the new
53 version.
54 list to see which packages are within the commit(s) (works like yum
56 list). At least one commit must be specified, but more than one or
57 a range will also work.
58 version to see the rpmdb version of the packages within the commit
60 (works like yum version nogroups). At least one commit must be
61 specified, but more than one or a range will also work.
62 deploy
64 Takes version, branch, or commit ID as an argument, and creates a
65 new deployment using it, setting it up as the default for the next
66 boot. Unlike most other commands, this will automatically fetch and
67 traverse the origin history to find the target. By design, this has
68 no effect on your running filesystem tree. You must reboot for any
69 changes to take effect.
70 This will also queue an update for any layered packages.
72 --unchanged-exit-77 to exit status 77 to indicate that the system
74 is already on the specified commit. This tristate return model is
75 intended to support idempotency-oriented systems automation tools
76 like Ansible.
77 --reboot or -r to initiate a reboot after the upgrade is prepared.
79 --preview download enough metadata to inspect the RPM diff, but do
81 not actually create a new deployment.
82 --cache-only or -C to perform the operation without trying to
84 download the target tree from the remote nor the latest packages.
85 --download-only to only download the target ostree and layered RPMs
87 without actually performing the deployment. This can be used with a
88 subsequent --cache-only invocation to perform the operation
89 completely offline.
90 install
92 Takes one or more packages as arguments. The packages are fetched
93 from the enabled repositories in /etc/yum.repos.d/ and are
94 overlayed on top of a new deployment. It is also possible to
95 specify a local RPM package that resides on the host. Overlayed
96 packages can later be removed with the uninstall command.
97 If this is the first time a machine-local change is made, note that
99 this will change rpm-ostree to operate in full hybrid mode.
100 Concretely, rpm-ostree will also start fetching all enabled rpm-md
101 (yum) repositories and use those for package updates every time
102 rpm-ostree upgrade is invoked, as well as during other operations
103 such as rebase.
104 rpm-ostree remembers these requests even if a later host update
106 includes those packages already: if the packages are subsequently
107 dropped out again, rpm-ostree will go back to layering them.
108 Note that by default, specifying a package that is already in the
110 base layer is an error unless the --allow-inactive option is
111 provided. This can be useful when anticipating the removal of a
112 base package.
113 --idempotent to do nothing if a package request is already present
115 instead of erroring out.
116 --reboot or -r to initiate a reboot after the deployment is
118 prepared.
119 --dry-run or -n to exit after printing the transaction rather than
121 downloading the packages and creating a new deployment.
122 --allow-inactive to allow requests for packages that are already in
124 the base layer.
125 --cache-only or -C to perform the operation without trying to
127 download the latest packages.
128 --download-only to only download the target layered RPMs without
130 actually performing the deployment. This can be used with a
131 subsequent --cache-only invocation to perform the operation
132 completely offline.
133 --apply-live will perform a subsequent apply-live operation to
135 apply changes to the booted deployment.
136 --force-replacefiles allows one package to overwrite files from
138 another without having to rebuild the whole kernel package.
139 uninstall
141 Takes one or more packages as arguments. The packages are removed
142 from the set of packages that are currently overlayed. The
143 remaining packages in the set (if any) are fetched from the enabled
144 repositories in /etc/yum.repos.d/ and are overlayed on top of a new
145 deployment.
146 --reboot or -r to initiate a reboot after the deployment is
148 prepared.
149 --dry-run or -n to exit after printing the transaction rather than
151 downloading the packages and creating a new deployment.
152 search
154 Takes one or more query terms as arguments. The packages are
155 searched within the enabled repositories in /etc/yum.repos.d/.
156 Packages can be overlayed and removed using the install and
157 uninstall commands.
158 rebase
160 Switch to a different base image, while preserving all of the state
161 that upgrade does, such as /etc changes, any layered RPM packages,
162 etc.
163 For rebasing to container images, the syntax uses ostree container
165 image references, which combine container image transports (see man
166 skopeo) along with a required integrity scheme. The ostree model
167 encourages container images to be signed, because they must be
168 ultimately trusted.
169 ostree-image-signed:docker://quay.io/exampleos/custom:latest - this
171 will pull from a remote registry, and error out if the container
172 backend does not require signatures.
173 ostree-unverified-registry:quay.io/exampleos/custom:latest - this
175 will pull from a remote registry, and no signature will be
176 required. In practice, this is just a shorthand for
177 ostree-unverified-image:docker://quay.io/exampleos/custom:latest.
178 ostree-unverified-image:oci:/path/to/dir.oci Fetch from a local
180 unsigned OCI directory (integrity of this directory may have been
181 verified out of band).
182 For rebasing to OSTree branches, the full syntax is rebase
184 REMOTENAME:BRANCHNAME. Alternatively, you can use the --branch or
185 --remote options mentioned below. With the argument syntax,
186 specifying just BRANCHNAME will reuse the same remote. You may also
187 omit one of REMOTENAME or BRANCHNAME (keeping the colon). In the
188 former case, the branch refers to a local branch; in the latter
189 case, the same branch will be used on a different remote.
190 This will also queue an update for any layered packages.
192 --branch or -b to pick a branch name.
194 --remote or -m to pick a remote name.
196 --cache-only or -C to perform the rebase without trying to download
198 the target tree from the remote nor the latest packages.
199 --download-only to only download the target ostree and layered RPMs
201 without actually performing the deployment. This can be used with a
202 subsequent --cache-only invocation to perform the operation
203 completely offline.
204 rollback
206 OSTree manages an ordered list of bootloader entries, called
207 "deployments". The entry at index 0 is the default bootloader
208 entry. Each entry has a separate /etc, but they all share a single
209 /var. You can use the bootloader to choose between entries by
210 pressing Tab to interrupt startup.
211 This command then changes the default bootloader entry. If the
213 current default is booted, then set the default to the previous
214 entry. Otherwise, make the currently booted tree the default.
215 --reboot or -r to initiate a reboot after rollback is prepared.
217 status
219 Gives information pertaining to the current deployment in use.
220 Lists the names and refspecs of all possible deployments in order,
221 such that the first deployment in the list is the default upon
222 boot. The deployment marked with * is the current booted
223 deployment, and marking with 'r' indicates the most recent upgrade
224 (the newest deployment version).
225 --verbose or -v to display more information, such as package diff,
227 advisories, GPG signature user IDs, and StateRoot names.
228 --advisories or -a to expand the advisories listing, if any.
230 --booted or -b to only print information about the booted
232 deployment.
233 --pending-exit-77 to exit status 77 if a pending deployment is
235 available. This can be useful in scripting.
236 --json to output the status information in JSON format for easier
238 scripting.
239 --jsonpath=EXPRESSION or -J to filter JSON output by JSONPath
241 expression.
242 upgrade
244 Download the latest version of the current tree, and deploy it,
245 setting it up as the default for the next boot. By design, this has
246 no effect on your running filesystem tree. You must reboot for any
247 changes to take effect.
248 --unchanged-exit-77 to exit status 77 to indicate that the system
250 is already up to date. This tristate return model is intended to
251 support idempotency-oriented systems automation tools like Ansible.
252 --reboot or -r to initiate a reboot after upgrade is prepared.
254 --allow-downgrade to permit deployment of chronologically older
256 trees.
257 --preview to download only /usr/share/rpm in order to do a
259 package-level diff between the two versions.
260 --check to just check if an upgrade is available, without
262 downloading it or performing a package-level diff. Using this flag
263 will force an update of the RPM metadata from the enabled repos in
264 /etc/yum.repos.d/, if there are any layered packages.
265 --cache-only or -C to perform the upgrade without trying to
267 download the latest tree from the remote nor the latest packages.
268 --download-only to only download the target ostree and layered RPMs
270 without actually performing the deployment. This can be used with a
271 subsequent --cache-only invocation to perform the operation
272 completely offline.
273 override
275 Provides subcommands for overriding (modifying) the base OSTree
276 layer. Such modifications should be done with care and are normally
277 not intended to be long-lasting. For example, one might replace a
278 base package with its older version to avoid a regression.
279 Overrides are automatically carried over during new deployments.
280 The subcommands are:
281 remove to remove base packages.
283 replace to replace base packages. Requires explicitly specifying a
285 set of RPMs to install via HTTP or local file paths. On Fedora
286 systems, it is also supported to pull from the Fedora Koji/Bodhi
287 systems. For example, rpm-ostree override replace
288 https://objstore.int.example.com/hotfixes/kernel.rpm, rpm-ostree
289 override replace ./podman.rpm, rpm-ostree override replace
290 https://bodhi.fedoraproject.org/updates/FEDORA-2020-XXXXXXX or
291 rpm-ostree override replace
292 https://koji.fedoraproject.org/koji/buildinfo?buildID=XXXXXXX
293 reset to reset previous overrides. Currently, the full NEVRA of the
295 target packages must be specified.
296 refresh-md
298 Download the latest rpm repo metadata if necessary and generate the
299 cache.
300 kargs
302 Without options, display current default kernel arguments. Modify
303 arguments using the following parameters which will create a new
304 deployment with the modified kernel arguments. Previous deployments
305 are never changed.
306 --editor to use an editor to modify the kernel arguments.
308 --append to append a kernel argument. For example,
310 --append=panic=1.
311 --append-if-missing to append a kernel argument if it is not
313 present.
314 --delete to delete a kernel argument. For example,
316 --delete=panic=1.
317 --delete-if-present to delete a kernel argument if it is already
319 present. For example, --delete-if-present=panic=1.
320 --replace to replace an existing kernel argument, it allows you to
322 pass a KEY=VALUE. Also, it supports "KEY=VALUE=NEWVALUE" to replace
323 the value of an argumnet only if one value exist for that argument.
324 For example, --replace=panic=1. or --replace=panic=1=0.
325 --unchanged-exit-77 to exit status 77 to indicate that the kernel
327 arguments have not changed.
328 By default, modifications are applied to the kernel arguments of
330 the default deployment to get the final arguments. Use
331 --deploy-index or --import-proc-cmdline to instead base them off of
332 a specific deployment or the current boot.
333 cleanup
335 Commands such as upgrade create new deployments, which affect the
336 next boot, and take up additional storage space. In some cases, you
337 may want to undo and clean up these operations. This command
338 supports both removing additional deployments such as the "pending"
339 deployment (the next boot) as well as the default rollback
340 deployment. Use -p/--pending to remove the pending deployment, and
341 -r/--rollback to remove the rollback.
342 The -b/--base option does not affect finished deployments, but will
344 clean up any transient allocated space that may result from
345 interrupted operations. If you want to free up disk space safely,
346 use this option first.
347 The -m/--repomd option cleans up cached RPM repodata and any
349 partially downloaded (but not imported) packages.
350 NOTE: the cleanup will not affect any deployments that have been
352 "pinned" via the ostree admin pin operation.
353 reload
355 Some configuration and state data such as /etc/ostree/remotes.d
356 changes may not be reflected until a daemon reload is invoked. Use
357 this command to initiate a reload.
358 usroverlay
360 Mount a writable overlay filesystem on /usr which is active only
361 for the remainder of the system boot. This is intended for
362 development, testing, and debugging. Changes will not persist
363 across upgrades, or rebooting in general.
364 One important goal of this is to support traditional rpm -Uvh
366 /path/to/rpms or equivalent where changes are applied live.
367 However, an intended future feature for rpm-ostree will be a
368 variant of rpm-ostree override which also supports applying changes
369 live, for the cases which one wants persistence as well.
370 This command is equivalent to ostree admin unlock.
372 initramfs
374 By default, the primary use case mode for rpm-ostree is to
375 replicate an initramfs as part of a base layer. However, some use
376 cases require locally regenerating it to add configuration or
377 drivers. Use rpm-ostree initramfs to inspect the current status.
378 Use --enable to turn on client side initramfs regeneration. This
380 runs dracut to create the new initramfs. A new deployment will be
381 generated with this new initramfs, and after reboot, further
382 upgrades will continue regenerating. You must reboot for the new
383 initramfs to take effect.
384 To append additional custom arguments to the initramfs program
386 (currently dracut), use --arg. For example, --arg=-I
387 --arg=/etc/someconfigfile.
388 The --disable option will disable regeneration. You must reboot for
390 the change to take effect.
391 Note that for the simpler use case of adding a few files to the
393 initramfs, you can use rpm-ostree initramfs-etc instead. It is more
394 lightweight and does not involve running dracut.
395 initramfs-etc
397 Add configuration (/etc) files into the initramfs without
398 regenerating the entire initramfs. This is useful to be able to
399 configure services backing the root block device as well as
400 early-boot services like systemd and journald.
401 Use --track to start tracking a specific file. Can be specified
403 multiple times. A new deployment will be generated. Use --untrack
404 or --untrack-all to stop tracking files.
405 When there are tracked files, any future created deployment (e.g.
407 when doing an upgrade) will ensure that they are synced. You can
408 additionally use --force-sync to simply generate a new deployment
409 with the latest versions of tracked files without upgrading.
410 apply-live
412 Given a target OSTree commit (defaults to the pending deployment),
413 create a transient overlayfs filesystem for the booted /usr, and
414 synchronize the changes from the source to the booted filesystem
415 tree. By default, to ensure safety, only package additions are
416 allowed.
417 --reset to reset the filesystem tree to the booted commit.
419 --target may be used to target an arbitrary OSTree commit. This is
421 an advanced feature, exposed mainly for testing.
422 --allow-replacement enables live updates and removals for existing
424 packages.
425 Example 1. Install postgresql live
427 $ rpm-ostree install postgresql-server
429 $ rpm-ostree apply-live
430 $ systemctl start postgresql # Some setup required
431 This is also the same as:
434 $ rpm-ostree install -A postgresql-server
436 Currently, this just synchronizes the filesystem; no systemd units
438 are restarted for example.
439 A major implicit benefit of the overlayfs approach is that if
441 something goes wrong in the middle of a apply-live operation, a
442 system reboot will implicitly remove the overlay, restoring the
443 system to the pristine deployment state.
444 ex
446 This command offers access to experimental features; command line
447 stability is not guaranteed. The available subcommands will be
448 listed by invoking rpm-ostree ex.
449
451 compose
452 Entrypoint for tree composition; most typically used on servers to
453 prepare trees for replication by client systems. The tree
454 subcommand processes a treefile, installs packages, and commits the
455 result to an OSTree repository. There are also split commands
456 install, postprocess, and commit.
457
459 rpm-ostree uses the libdnf shared library, which honors
460 /etc/yum.repos.d. Note that rpm-md (yum/dnf) repositories are only
461 checked if client-side package layering is enabled.
462 However, the behavior for GPG keys is slightly different from a
464 traditional rpm system. Essentially, all GPG keys in /etc/pki/rpm-gpg
465 are loaded and trusted. The .repo file should reference the file path
466 in there.
467 The rpm --import /path/to/key.gpg command will not function today on a
469 live/booted system because rpm tries to write directly to the RPM
470 database.
471 However, during a container build process, the RPM database is writable
473 and such changes will persist.
474
476 rpm-ostreed.conf(5) ostree(1), rpm(8)
477rpm-ostree RPM-OSTREE(1)