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

SERVER SIDE COMMANDS

318       compose
319           Entrypoint for tree composition; most typically used on servers to
320           prepare trees for replication by client systems. The tree
321           subcommand processes a treefile, installs packages, and commits the
322           result to an OSTree repository. There are also split commands
323           install, postprocess, and commit.
324

SEE ALSO

326       rpm-ostreed.conf(5) ostree(1), rpm(8)
327
328
329
330rpm-ostree                                                       RPM-OSTREE(1)
Impressum