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 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 --reboot or -r to initiate a reboot after the upgrade is prepared.
78 --preview download enough metadata to inspect the RPM diff, but do
80 not actually create a new deployment.
81 --cache-only or -C to perform the operation without trying to
83 download the target tree from the remote nor the latest packages.
84 --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 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 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 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 --reboot or -r to initiate a reboot after the deployment is
107 prepared.
108 --dry-run or -n to exit after printing the transaction rather than
110 downloading the packages and creating a new deployment.
111 --allow-inactive to allow requests for packages that are already in
113 the base layer.
114 --cache-only or -C to perform the operation without trying to
116 download the latest packages.
117 --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 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 --reboot or -r to initiate a reboot after the deployment is
131 prepared.
132 --dry-run or -n to exit after printing the transaction rather than
134 downloading the packages and creating a new deployment.
135 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 replace Replace a package in the base tree.
141 reset Undo a remove or replace operation.
143 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 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 --branch or -b to to pick a branch name.
158 --remote or -m to to pick a remote name.
160 --cache-only or -C to perform the rebase without trying to download
162 the target tree from the remote nor the latest packages.
163 --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 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 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 --reboot or -r to initiate a reboot after rollback is prepared.
181 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 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 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 --reboot or -r to initiate a reboot after upgrade is prepared.
201 --allow-downgrade to permit deployment of chronologically older
203 trees.
204 --preview to download only /usr/share/rpm in order to do a
206 package-level diff between the two versions.
207 --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 --cache-only or -C to perform the upgrade without trying to
214 download the latest tree from the remote nor the latest packages.
215 --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 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 remove to remove base packages.
230 replace to replace base packages. Currently, only local RPM
232 replacements are supported: one must directly provide the RPMs to
233 substitute in.
234 reset to reset previous overrides. Currently, the full NEVRA of the
236 target packages must be specified.
237 refresh-md
239 Download the latest rpm repo metadata if necessary and generate the
240 cache.
241 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 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 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 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 The -m/--repomd option cleans up cached RPM repodata and any
268 partially downloaded (but not imported) packages.
269 NOTE: the cleanup will not affect any deployments that have been
271 "pinned" via the ostree admin pin operation.
272 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 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 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 This command is equivalent to ostree admin unlock.
291 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 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 To append additional custom arguments to the initramfs program
304 (currently dracut), use --arg. For example, --arg=-I
305 --arg=/etc/someconfigfile.
306 The --disable option will disable regeneration. You must reboot for
308 the change to take effect.
309 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
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
326 rpm-ostreed.conf(5) ostree(1), rpm(8)
327rpm-ostree RPM-OSTREE(1)