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

SERVER SIDE COMMANDS

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

SEE ALSO

382       rpm-ostreed.conf(5) ostree(1), rpm(8)
383
384
385
386rpm-ostree                                                       RPM-OSTREE(1)
Impressum