1RPM-OSTREE(1)                     rpm-ostree                     RPM-OSTREE(1)
2
3
4

NAME

6       rpm-ostree - Hybrid image/package system for host operating system
7       updates
8

SYNOPSIS

10       rpm-ostree {COMMAND} [OPTIONS...]
11

DESCRIPTION

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
20       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
24       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
33       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

CLIENT SIDE COMMANDS

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
43       db
44           Gives information pertaining to rpm data within the file system
45           trees within the ostree commits. There are three sub-commands:
46
47           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
55           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
59           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
63       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
71            --unchanged-exit-77 to exit status 77 to indicate that the system
72           is already on the specified commit. This tristate return model is
73           intended to support idempotency-oriented systems automation tools
74           like Ansible.
75
76           --reboot or -r to initiate a reboot after the upgrade is prepared.
77
78           --preview download enough metadata to inspect the RPM diff, but do
79           not actually create a new deployment.
80
81           --cache-only or -C to perform the operation without trying to
82           download the target tree from the remote nor the latest packages.
83
84           --download-only to only download the target ostree and layered RPMs
85           without actually performing the deployment. This can be used with a
86           subsequent --cache-only invocation to perform the operation
87           completely offline.
88
89       install
90           Takes one or more packages as arguments. The packages are fetched
91           from the enabled repositories in /etc/yum.repos.d/ and are
92           overlayed on top of a new deployment. It is also possible to
93           specify a local RPM package that resides on the host. Overlayed
94           packages can later be removed with the uninstall command.
95
96           If this is the first time a machine-local change is made, note that
97           this will change rpm-ostree to operate in full hybrid mode.
98           Concretely, rpm-ostree will also start fetching all enabled rpm-md
99           (yum) repositories and use those for package updates every time
100           rpm-ostree upgrade is invoked.
101
102           rpm-ostree remembers these requests even if a later host update
103           includes those packages already: if the packages are subsequently
104           dropped out again, rpm-ostree will go back to layering them.
105
106           Note that by default, specifying a package that is already in the
107           base layer is an error unless the --allow-inactive option is
108           provided. This can be useful when anticipating the removal of a
109           base package.
110
111           --idempotent to do nothing if a package request is already present
112           instead of erroring out.
113
114           --reboot or -r to initiate a reboot after the deployment is
115           prepared.
116
117           --dry-run or -n to exit after printing the transaction rather than
118           downloading the packages and creating a new deployment.
119
120           --allow-inactive to allow requests for packages that are already in
121           the base layer.
122
123           --cache-only or -C to perform the operation without trying to
124           download the latest packages.
125
126           --download-only to only download the target layered RPMs without
127           actually performing the deployment. This can be used with a
128           subsequent --cache-only invocation to perform the operation
129           completely offline.
130
131           --apply-live will perform a subsequent apply-live operation to
132           apply changes to the booted deployment.
133
134       uninstall
135           Takes one or more packages as arguments. The packages are removed
136           from the set of packages that are currently overlayed. The
137           remaining packages in the set (if any) are fetched from the enabled
138           repositories in /etc/yum.repos.d/ and are overlayed on top of a new
139           deployment.
140
141           --reboot or -r to initiate a reboot after the deployment is
142           prepared.
143
144           --dry-run or -n to exit after printing the transaction rather than
145           downloading the packages and creating a new deployment.
146
147       override
148           remove Remove a package from the base tree. Note that this is
149           similar to layering in that the original base is retained.
150
151           replace Replace a package in the base tree.
152
153           reset Undo a remove or replace operation.
154
155       rebase
156           Switch to a different branch (possibly using a new remote), while
157           preserving all of the state that upgrade does, such as /etc
158           changes, any layered RPM packages, etc.
159
160           The full syntax is rebase REMOTENAME:BRANCHNAME. Alternatively, you
161           can use the --branch or --remote options mentioned below. With the
162           argument syntax, specifying just BRANCHNAME will reuse the same
163           remote. You may also omit one of REMOTENAME or BRANCHNAME (keeping
164           the colon). In the former case, the branch refers to a local
165           branch; in the latter case, the same branch will be used on a
166           different remote.
167
168           --branch or -b to to pick a branch name.
169
170           --remote or -m to to pick a remote name.
171
172           --cache-only or -C to perform the rebase without trying to download
173           the target tree from the remote nor the latest packages.
174
175           --download-only to only download the target ostree and layered RPMs
176           without actually performing the deployment. This can be used with a
177           subsequent --cache-only invocation to perform the operation
178           completely offline.
179
180       rollback
181           OSTree manages an ordered list of bootloader entries, called
182           "deployments". The entry at index 0 is the default bootloader
183           entry. Each entry has a separate /etc, but they all share a single
184           /var. You can use the bootloader to choose between entries by
185           pressing Tab to interrupt startup.
186
187           This command then changes the default bootloader entry. If the
188           current default is booted, then set the default to the previous
189           entry. Otherwise, make the currently booted tree the default.
190
191           --reboot or -r to initiate a reboot after rollback is prepared.
192
193       status
194           Gives information pertaining to the current deployment in use.
195           Lists the names and refspecs of all possible deployments in order,
196           such that the first deployment in the list is the default upon
197           boot. The deployment marked with * is the current booted
198           deployment, and marking with 'r' indicates the most recent upgrade
199           (the newest deployment version).
200
201       upgrade
202           Download the latest version of the current tree, and deploy it,
203           setting it up as the default for the next boot. By design, this has
204           no effect on your running filesystem tree. You must reboot for any
205           changes to take effect.
206
207            --unchanged-exit-77 to exit status 77 to indicate that the system
208           is already up to date. This tristate return model is intended to
209           support idempotency-oriented systems automation tools like Ansible.
210
211           --reboot or -r to initiate a reboot after upgrade is prepared.
212
213           --allow-downgrade to permit deployment of chronologically older
214           trees.
215
216           --preview to download only /usr/share/rpm in order to do a
217           package-level diff between the two versions.
218
219           --check to just check if an upgrade is available, without
220           downloading it or performing a package-level diff. Using this flag
221           will force an update of the RPM metadata from the enabled repos in
222           /etc/yum.repos.d/, if there are any layered packages.
223
224           --cache-only or -C to perform the upgrade without trying to
225           download the latest tree from the remote nor the latest packages.
226
227           --download-only to only download the target ostree and layered RPMs
228           without actually performing the deployment. This can be used with a
229           subsequent --cache-only invocation to perform the operation
230           completely offline.
231
232       override
233           Provides subcommands for overriding (modifying) the base OSTree
234           layer. Such modifications should be done with care and are normally
235           not intended to be long-lasting. For example, one might replace a
236           base package with its older version to avoid a regression.
237           Overrides are automatically carried over during new deployments.
238           The subcommands are:
239
240           remove to remove base packages.
241
242           replace to replace base packages. Currently, only local RPM
243           replacements are supported: one must directly provide the RPMs to
244           substitute in.
245
246           reset to reset previous overrides. Currently, the full NEVRA of the
247           target packages must be specified.
248
249       refresh-md
250           Download the latest rpm repo metadata if necessary and generate the
251           cache.
252
253       kargs
254           Without options, display current default kernel arguments. Modify
255           arguments using --append, --replace, --delete, or --editor. This
256           will create a new deployment with the modified kernel arguments.
257           Previous deployments are never changed.
258
259           By default, modifications are applied to the kernel arguments of
260           the default deployment to get the final arguments. Use
261           --deploy-index or --import-proc-cmdline to instead base them off of
262           a specific deployment or the current boot.
263
264       cleanup
265           Commands such as upgrade create new deployments, which affect the
266           next boot, and take up additional storage space. In some cases, you
267           may want to undo and clean up these operations. This command
268           supports both removing additional deployments such as the "pending"
269           deployment (the next boot) as well as the default rollback
270           deployment. Use -p/--pending to remove the pending deployment, and
271           -r/--rollback to remove the rollback.
272
273           The -b/--base option does not affect finished deployments, but will
274           clean up any transient allocated space that may result from
275           interrupted operations. If you want to free up disk space safely,
276           use this option first.
277
278           The -m/--repomd option cleans up cached RPM repodata and any
279           partially downloaded (but not imported) packages.
280
281           NOTE: the cleanup will not affect any deployments that have been
282           "pinned" via the ostree admin pin operation.
283
284       reload
285           Some configuration and state data such as /etc/ostree/remotes.d
286           changes may not be reflected until a daemon reload is invoked. Use
287           this command to initiate a reload.
288
289       usroverlay
290           Mount a writable overlay filesystem on /usr which is active only
291           for the remainder of the system boot. This is intended for
292           development, testing, and debugging. Changes will not persist
293           across upgrades, or rebooting in general.
294
295           One important goal of this is to support traditional rpm -Uvh
296           /path/to/rpms or equivalent where changes are applied live.
297           However, an intended future feature for rpm-ostree will be a
298           variant of rpm-ostree override which also supports applying changes
299           live, for the cases which one wants persistence as well.
300
301           This command is equivalent to ostree admin unlock.
302
303       initramfs
304           By default, the primary use case mode for rpm-ostree is to
305           replicate an initramfs as part of a base layer. However, some use
306           cases require locally regenerating it to add configuration or
307           drivers. Use rpm-ostree initramfs to inspect the current status.
308
309           Use --enable to turn on client side initramfs regeneration. A new
310           deployment will be generated, and after reboot, further upgrades
311           will continue regenerating. You must reboot for the new initramfs
312           to take effect.
313
314           To append additional custom arguments to the initramfs program
315           (currently dracut), use --arg. For example, --arg=-I
316           --arg=/etc/someconfigfile.
317
318           The --disable option will disable regeneration. You must reboot for
319           the change to take effect.
320
321       ex
322           This command offers access to experimental features; command line
323           stability is not guaranteed. The available subcommands will be
324           listed by invoking rpm-ostree ex. For example, there is rpm-ostree
325           ex apply-live which is an experimental interface for applying
326           changes to the booted deployment.
327
328       ex apply-live
329           Experimental feature; subject to change.
330
331           Given a target OSTree commit (defaults to the pending deployment),
332           create a transient overlayfs filesystem for /usr, and synchronize
333           the changes to the booted filesystem tree. By default, to ensure
334           safety, only package additions are allowed.
335
336           --reset to reset the filesystem tree to the booted commit.
337
338           --target may be used to target an arbitrary OSTree commit. This is
339           an advanced feature, exposed mainly for testing.
340
341           --allow-replacement enables live updates and removals for existing
342           packages.
343
344           Example 1. Install postgresql live
345
346               $ rpm-ostree install postgresql-server
347               $ rpm-ostree ex apply-live
348               $ systemctl start postgresql  # Some setup required
349
350
351           Currently, this just synchronizes the filesystem; no systemd units
352           are restarted for example.
353
354           A major implicit benefit of the overlayfs approach is that if
355           something goes wrong in the middle of a apply-live operation, a
356           system reboot will implicitly remove the overlay, restoring the
357           system to the pristine deployment state.
358
359       ex initramfs-etc
360           Experimental feature; subject to change.
361
362           Add configuration (/etc) files into the initramfs without
363           regenerating the entire initramfs. This is useful to be able to
364           configure services backing the root block device as well as
365           early-boot services like systemd and journald.
366
367           Use --track to start tracking a specific file. Can be specified
368           multiple times. A new deployment will be generated. Use --untrack
369           or --untrack-all to stop tracking files.
370
371           When there are tracked files, any future created deployment (e.g.
372           when doing an upgrade) will ensure that they are synced. You can
373           additionally use --force-sync to simply generate a new deployment
374           with the latest versions of tracked files without upgrading.
375

SERVER SIDE COMMANDS

377       compose
378           Entrypoint for tree composition; most typically used on servers to
379           prepare trees for replication by client systems. The tree
380           subcommand processes a treefile, installs packages, and commits the
381           result to an OSTree repository. There are also split commands
382           install, postprocess, and commit.
383

SEE ALSO

385       rpm-ostreed.conf(5) ostree(1), rpm(8)
386
387
388
389rpm-ostree                                                       RPM-OSTREE(1)
Impressum