Skip to content

Commit c7fbe27

Browse files
jasonbrooksjasonbrooks
authored
Merge pull request #89 from miabbott/rpm_ostree_cmd_ref_37
First shot at rpm-ostree command reference
2 parents efa7c41 + 501e333 commit c7fbe27

File tree

1 file changed

+328
-0
lines changed

1 file changed

+328
-0
lines changed

‎references/rpm_ostree_command_ref.adoc

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
[[rpm-ostree-command-ref]]
2+
= {product-title} rpm-ostree Command Reference
3+
{product-author}
4+
{product-version}
5+
:data-uri:
6+
:icons:
7+
8+
== Primary 'rpm-ostree' commands
9+
10+
At the moment, there are four primary commands to be familiar with on
11+
an `rpm-ostree` based system. Also remember that in a Project Atomic
12+
system, the `atomic host` command (from the
13+
link:https://github.com/projectatomic/atomic/[`atomic` command]) is an
14+
alias for `rpm-ostree`.
15+
16+
17+
=== `rpm-ostree status`
18+
19+
The `rpm-ostree status` command will show you your deployments in the order in
20+
which they will appear in the bootloader, the first deployment in the list being
21+
the current default one. The `●` shows the currently booted deployment. This
22+
command can be run as a non-root user, unlike other `rpm-ostree` commands.
23+
24+
The `rpm-ostree status` command also supports formatting the output in JSON
25+
format using the `--json` flag.
26+
27+
You can see the example output from a Fedora 26 Atomic Host system:
28+
29+
....
30+
# rpm-ostree status
31+
State: idle
32+
Deployments:
33+
● fedora-atomic:fedora/26/x86_64/atomic-host
34+
Version: 26.110 (2017-08-20 18:10:09)
35+
Commit: 13ed0f241c9945fd5253689ccd081b5478e5841a71909020e719437bbeb74424
36+
....
37+
38+
39+
=== `rpm-ostree upgrade`
40+
41+
The `rpm-ostree upgrade` command will perform a system upgrade, creating a
42+
*new* deployment (root filesystem) and set it as the default for the next boot.
43+
You should use `systemctl reboot` shortly afterwards. Alteratively, you can use
44+
the `-r` flag to force a reboot immediately after the upgrade has completed.
45+
46+
You can see some example output for an upgrade on a Fedora 26 Atomic Host below:
47+
48+
....
49+
# rpm-ostree upgrade
50+
1 metadata, 0 content objects fetched; 569 B transferred in 1 seconds
51+
Copying /etc changes: 24 modified, 0 removed, 56 added
52+
Transaction complete; bootconfig swap: yes deployment count change: 0
53+
Upgraded:
54+
glibc 2.25-7.fc26 -> 2.25-8.fc26
55+
glibc-all-langpacks 2.25-7.fc26 -> 2.25-8.fc26
56+
glibc-common 2.25-7.fc26 -> 2.25-8.fc26
57+
krb5-libs 1.15.1-21.fc26 -> 1.15.1-22.fc26
58+
libcrypt-nss 2.25-7.fc26 -> 2.25-8.fc26
59+
python2-setuptools 36.2.0-1.fc26 -> 36.2.0-2.fc26
60+
python3 3.6.2-1.fc26 -> 3.6.2-5.fc26
61+
python3-libs 3.6.2-1.fc26 -> 3.6.2-5.fc26
62+
python3-setuptools 36.2.0-1.fc26 -> 36.2.0-2.fc26
63+
system-python 3.6.2-1.fc26 -> 3.6.2-5.fc26
64+
system-python-libs 3.6.2-1.fc26 -> 3.6.2-5.fc26
65+
tmux 2.5-1.fc26 -> 2.5-4.fc26
66+
Run "systemctl reboot" to start a reboot
67+
....
68+
69+
=== `rpm-ostree rollback`
70+
71+
The `rpm-ostree rollback` command will roll back the system to the previous state,
72+
i.e. the default deployment changes places with the non-default one. By default, the
73+
`rpm-ostree upgrade` will keep at most two bootable "deployments", though the underlying
74+
technology supports more. Like the `rpm-ostree upgrade` command, the system needs to be
75+
rebooted in order to make the newly selected deployment active. You can also use the
76+
`-r` flag to reboot the system immediately after the rollback completes.
77+
78+
You can see some example output of a rollback on a Fedora 26 Atomic Host:
79+
80+
....
81+
# rpm-ostree rollback
82+
Moving '080cf9c61a5e38f8101290db5025a71fc6cfb189a9393785ba347d006d6285ee.0' to be first deployment
83+
Transaction complete; bootconfig swap: yes deployment count change: 0
84+
Downgraded:
85+
glibc 2.25-8.fc26 -> 2.25-7.fc26
86+
glibc-all-langpacks 2.25-8.fc26 -> 2.25-7.fc26
87+
glibc-common 2.25-8.fc26 -> 2.25-7.fc26
88+
krb5-libs 1.15.1-22.fc26 -> 1.15.1-21.fc26
89+
libcrypt-nss 2.25-8.fc26 -> 2.25-7.fc26
90+
python2-setuptools 36.2.0-2.fc26 -> 36.2.0-1.fc26
91+
python3 3.6.2-5.fc26 -> 3.6.2-1.fc26
92+
python3-libs 3.6.2-5.fc26 -> 3.6.2-1.fc26
93+
python3-setuptools 36.2.0-2.fc26 -> 36.2.0-1.fc26
94+
system-python 3.6.2-5.fc26 -> 3.6.2-1.fc26
95+
system-python-libs 3.6.2-5.fc26 -> 3.6.2-1.fc26
96+
tmux 2.5-4.fc26 -> 2.5-1.fc26
97+
Run "systemctl reboot" to start a reboot
98+
....
99+
100+
=== `rpm-ostree deploy <version>`
101+
102+
The `rpm-ostree deploy` command makes use of the server-side history
103+
feature of OSTree. It will search the history of the current branch for
104+
a commit with the specified version, and deploy it. This can be used
105+
in scripts to ensure consistent updates. For example, if the upstream
106+
OS vendor provides an update online, you might not want to deploy it until
107+
you've tested it. This helps ensure that when you upgrade, you are
108+
getting exactly what you asked for.
109+
110+
You can see the some example output of a deploy on a Fedora 26 Atomic Host:
111+
112+
....
113+
# rpm-ostree deploy 26.109
114+
Resolving version '26.109'
115+
1 metadata, 0 content objects fetched; 569 B transferred in 3 seconds
116+
117+
138 metadata, 2011 content objects fetched; 114566 KiB transferred in 672 seconds
118+
Copying /etc changes: 24 modified, 0 removed, 55 added
119+
Transaction complete; bootconfig swap: yes deployment count change: 1
120+
Freed objects: 2.3 kB
121+
Downgraded:
122+
glibc 2.25-8.fc26 -> 2.25-7.fc26
123+
glibc-all-langpacks 2.25-8.fc26 -> 2.25-7.fc26
124+
glibc-common 2.25-8.fc26 -> 2.25-7.fc26
125+
krb5-libs 1.15.1-22.fc26 -> 1.15.1-21.fc26
126+
libcrypt-nss 2.25-8.fc26 -> 2.25-7.fc26
127+
python2-setuptools 36.2.0-2.fc26 -> 36.2.0-1.fc26
128+
python3 3.6.2-5.fc26 -> 3.6.2-1.fc26
129+
python3-libs 3.6.2-5.fc26 -> 3.6.2-1.fc26
130+
python3-setuptools 36.2.0-2.fc26 -> 36.2.0-1.fc26
131+
system-python 3.6.2-5.fc26 -> 3.6.2-1.fc26
132+
system-python-libs 3.6.2-5.fc26 -> 3.6.2-1.fc26
133+
tmux 2.5-4.fc26 -> 2.5-1.fc26
134+
Run "systemctl reboot" to start a reboot
135+
....
136+
137+
== Hybrid image/packaging via package layering
138+
139+
It is possible to dynamically add more packages onto the system that are not
140+
part of the commit composed on the server. These additional "layered" packages
141+
are persistent across upgrades, rebases, and deploys (contrast with the
142+
link:https://github.com/ostreedev/ostree/blob/master/man/ostree-admin-unlock.xml[ostree unlocking]
143+
mechanism).
144+
145+
This is where the true hybrid image/package nature of `rpm-ostree` comes into
146+
play; you get a combination of the benefits of images and packages. The
147+
package updates are still fully transactional and offline.
148+
149+
For example, you can use package layering to install 3rd party
150+
kernel modules, or userspace driver daemons such as `pcsc-lite-ccid`.
151+
While most software should go into a container, you have full flexibilty
152+
to use packages where it suits.
153+
154+
See the link:../using_ostree/rebasing/package_layering.html[package layering section] for more information on package layering.
155+
156+
157+
=== `rpm-ostree install/uninstall <pkg>`
158+
159+
The `rpm-ostree install` command will download the target package, its dependencies,
160+
and create a new deployment with those packages installed. Additionally, you can use
161+
the `rpm-ostree install` to layer local RPMs onto the system. To remove layered
162+
packages, use `rpm-ostree uninstall`.
163+
164+
By default, every `rpm-ostree` operation is "offline" - it has no effect
165+
on your running system, and will only take effect when you reboot. This
166+
"pending" state is called the "pending deployment". Operations can be chained;
167+
for example, if you invoke `rpm-ostree upgrade` after installing a package, your
168+
new root will upgraded with the package also installed.
169+
170+
171+
== Rebasing via `rpm-ostree rebase`
172+
173+
Your operating system vendor may provide multiple base branches. For example,
174+
Fedora Atomic Host has branches of the form:
175+
176+
- `fedora/26/x86_64/atomic-host`
177+
- `fedora/26/x86_64/updates/atomic-host`
178+
- `fedora/27/x86_64/atomic-host`
179+
180+
You can use the `rebase` command to switch between these; this can represent a
181+
major version upgrade, or logically switching between different "testing"
182+
streams within the same release. Like every other `rpm-ostree` operation, All
183+
layered packages and local state will be carried across.
184+
185+
The `rebase` command also allows you to switch your system to an entirely new
186+
OS distribution. This means it is possible to switch your Fedora 26 Atomic Host
187+
to a version of CentOS Atomic Host. While this is not likely to be done on a
188+
production system, it can be useful in certain testing scenarios.
189+
190+
191+
== Other local state changes
192+
193+
=== `rpm-ostree cleanup`
194+
195+
The `rpm-ostree cleanup` command allows the user to remove data generated by
196+
`rpm-ostree` operations which is no longer used. This includes non-booted
197+
deployments, cached RPM repodata, partially downloaded RPMs, or transient
198+
allocated data as result of interrupted operations.
199+
200+
The `-b` flag will remove the data remaining from interrupted operations.
201+
If you want to free up space on your system, use this options first.
202+
203+
The `-m` flag will remove the cached RPM repodata and partially downloaded
204+
RPMs.
205+
206+
The `-p` flag will remove the pending deployment (usually as a result of an
207+
upgrade or an install operation).
208+
209+
The `-r` flag will remove the rollback deployment.
210+
211+
You can combine all the flags in a single operation to cleanup all the data
212+
that can be cleaned up.
213+
214+
215+
=== `rpm-ostree initramfs`
216+
217+
The `rpm-ostree intitramfs` command is primarily used to enable the regeneration
218+
of the initramfs after its configuration has changed or a kernel driver has been added.
219+
220+
You can query the state of initramfs regeneration by using the command without any
221+
options.
222+
223+
You can enable/disable the regeneration by using the `--enable` or `--disable`
224+
options respectively.
225+
226+
=== `rpm-ostree reload`
227+
228+
The `rpm-ostree reload` command is used to reload the `rpm-ostreed` daemon that runs
229+
on a system. This should be done when configuration of the daemon changes, for example
230+
when something a remote configuration in `/etc/ostree/remotes.d` has been modified.
231+
232+
233+
== Querying the RPM database
234+
235+
The `rpm-ostree db` command allows the user to inspect RPM data of the ostree commit/deployment.
236+
237+
=== `rpm-ostree db diff <commit> <commit>`
238+
239+
The `rpm-ostree db diff` command allows the user to compare the differences of the package
240+
set between two commits. By default, the output will show the packages which have been
241+
upgrade, downgraded, added, or removed between the commits.
242+
243+
Example output on Fedora 26 Atomic Host:
244+
245+
....
246+
# rpm-ostree db diff 080cf9c61a5e 13ed0f241c | head -n 10
247+
ostree diff commit old: 080cf9c61a5e (080cf9c61a5e38f8101290db5025a71fc6cfb189a9393785ba347d006d6285ee)
248+
ostree diff commit new: 13ed0f241c (13ed0f241c9945fd5253689ccd081b5478e5841a71909020e719437bbeb74424)
249+
Upgraded:
250+
glibc 2.25-7.fc26.x86_64 -> 2.25-8.fc26.x86_64
251+
glibc-all-langpacks 2.25-7.fc26.x86_64 -> 2.25-8.fc26.x86_64
252+
glibc-common 2.25-7.fc26.x86_64 -> 2.25-8.fc26.x86_64
253+
krb5-libs 1.15.1-21.fc26.x86_64 -> 1.15.1-22.fc26.x86_64
254+
libcrypt-nss 2.25-7.fc26.x86_64 -> 2.25-8.fc26.x86_64
255+
python2-setuptools 36.2.0-1.fc26.noarch -> 36.2.0-2.fc26.noarch
256+
python3 3.6.2-1.fc26.x86_64 -> 3.6.2-5.fc26.x86_64
257+
....
258+
259+
=== `rpm-ostree db list <commit>`
260+
261+
The `rpm-ostree db list` command will list all the packages and their versions that are
262+
contained in a commit.
263+
264+
Example output from Fedora 26 Atomic Host:
265+
266+
....
267+
# rpm-ostree db list 080cf9c61a5e | head -n 10
268+
ostree commit: 080cf9c61a5e (080cf9c61a5e38f8101290db5025a71fc6cfb189a9393785ba347d006d6285ee)
269+
GeoIP-1.6.11-1.fc26.x86_64
270+
GeoIP-GeoLite-data-2017.07-1.fc26.noarch
271+
NetworkManager-1:1.8.2-1.fc26.x86_64
272+
NetworkManager-libnm-1:1.8.2-1.fc26.x86_64
273+
NetworkManager-team-1:1.8.2-1.fc26.x86_64
274+
acl-2.2.52-15.fc26.x86_64
275+
atomic-1.18.1-5.fc26.x86_64
276+
atomic-devmode-0.3.7-1.fc26.noarch
277+
atomic-registries-1.18.1-5.fc26.x86_64
278+
....
279+
280+
=== `rpm-ostree db version <commit>`
281+
282+
The `rpm-ostree db version` command will display the version of the RPM database for the
283+
ostree commit provided.
284+
285+
Example output from Fedora 26 Atomic Host:
286+
287+
....
288+
# rpm-ostree db version 080cf9c61a5e
289+
ostree commit: 080cf9c61a5e (080cf9c61a5e38f8101290db5025a71fc6cfb189a9393785ba347d006d6285ee)
290+
rpmdbv is: 463:0a72e882be36a47eb580d89f0304a9876660f751
291+
....
292+
293+
== Composing an ostree commit
294+
295+
The `rpm-ostree` command has support for generating an ostree commit that can be used by
296+
existing Atomic Hosts. The only input required is a JSON formatted 'treefile' which defines
297+
how the compose will be constructed.
298+
299+
See the section on link:../using_ostree/creating_own_distribution/ostree_compose.html[ostree compose] for more details.
300+
301+
=== `rpm-ostree compose tree <treefile>`
302+
303+
The `rpm-ostree compose tree` command will install RPMs into a filesystem and commit that filesystem via ostree.
304+
305+
== Experimental interface
306+
307+
There is a generic `rpm-ostree ex` command that offers experimental features. These features are not production read
308+
and should be treated as such. These commands may or may not be promoted to supported, which means they may be dropped
309+
from the tool altogether in the future.
310+
311+
=== `rpm-ostree ex livefs`
312+
313+
The `rpm-ostree ex livefs` command will apply any pending changes (for example, a package layered via `rpm-ostree install`)
314+
to the currently booted deployment. This allows the user to install packages and begin using them without having to reboot the
315+
system.
316+
317+
=== `rpm-ostree ex override`
318+
319+
The `rpm-ostree ex override` command allows the user to override the current package set of a deployment by removing or replacing
320+
packages from the base package set. Using these overrides requires that ther user reboot the system, as `rpm-ostree ex livefs` only
321+
supports packages that have been added via `rpm-ostree install`.
322+
323+
`rpm-ostree ex override remove` will remove a package from the base package set of a deployment.
324+
325+
`rpm-ostree ex override replace` will replace a package in the base package set of a deployment.
326+
327+
`rpm-ostree ex override reset` will reset any package overrides that have been made.
328+

0 commit comments

Comments
 (0)