First shot at rpm-ostree command reference

references/rpm_ostree_command_ref.adoc

@@ -0,0 +1,251 @@
+[[rpm-ostree-command-ref]]
+= {product-title} rpm-ostree Command Reference
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+
+== Primary 'rpm-ostree' commands
+
+At the moment, there are four primary commands to be familiar with on
+an `rpm-ostree` based system.  Also remember that in a Project Atomic
+system, the `atomic host` command (from the
+link:https://github.com/projectatomic/atomic/[`atomic` command]) is an
+alias for `rpm-ostree`.
+
+
+=== `rpm-ostree status`
+
+The `rpm-ostree status` command will show you your deployments in the order in
+which they will appear in the bootloader, the first deployment in the list being
+the current default one. The `●` shows the currently booted deployment.  This
+command can be run as a non-root user, unlike other `rpm-ostree` commands.
+
+The `rpm-ostree status` command also supports formatting the output in JSON
+format using the `--json` flag.
+
+You can see the example output from a Fedora 26 Atomic Host system:
+
+....
+# rpm-ostree status
+State: idle
+Deployments:
+● fedora-atomic:fedora/26/x86_64/atomic-host
+                   Version: 26.110 (2017-08-20 18:10:09)
+                    Commit: 13ed0f241c9945fd5253689ccd081b5478e5841a71909020e719437bbeb74424
+....
+
+
+=== `rpm-ostree upgrade`
+
+The `rpm-ostree upgrade` command will perform a system upgrade, creating a
+*new* deployment (root filesystem) and set it as the default for the next boot.
+You should use `systemctl reboot` shortly afterwards.  Alteratively, you can use
+the `-r` flag to force a reboot immediately after the upgrade has completed.
+
+You can see some example output for an upgrade on a Fedora 26 Atomic Host below:
+
+....
+# rpm-ostree upgrade
+1 metadata, 0 content objects fetched; 569 B transferred in 1 seconds
+Copying /etc changes: 24 modified, 0 removed, 56 added
+Transaction complete; bootconfig swap: yes deployment count change: 0
+Upgraded:
+  glibc 2.25-7.fc26 -> 2.25-8.fc26
+  glibc-all-langpacks 2.25-7.fc26 -> 2.25-8.fc26
+  glibc-common 2.25-7.fc26 -> 2.25-8.fc26
+  krb5-libs 1.15.1-21.fc26 -> 1.15.1-22.fc26
+  libcrypt-nss 2.25-7.fc26 -> 2.25-8.fc26
+  python2-setuptools 36.2.0-1.fc26 -> 36.2.0-2.fc26
+  python3 3.6.2-1.fc26 -> 3.6.2-5.fc26
+  python3-libs 3.6.2-1.fc26 -> 3.6.2-5.fc26
+  python3-setuptools 36.2.0-1.fc26 -> 36.2.0-2.fc26
+  system-python 3.6.2-1.fc26 -> 3.6.2-5.fc26
+  system-python-libs 3.6.2-1.fc26 -> 3.6.2-5.fc26
+  tmux 2.5-1.fc26 -> 2.5-4.fc26
+Run "systemctl reboot" to start a reboot
+....
+
+=== `rpm-ostree rollback`
+
+The `rpm-ostree rollback` command will roll back the system to the previous state,
+i.e. the default deployment changes places with the non-default one.  By default, the
+`rpm-ostree upgrade` will keep at most two bootable "deployments", though the underlying
+technology supports more.  Like the `rpm-ostree upgrade` command, the system needs to be
+rebooted in order to make the newly selected deployment active.  You can also use the
+`-r` flag to reboot the system immediately after the rollback completes.
+
+You can see some example output of a rollback on a Fedora 26 Atomic Host:
+
+....
+# rpm-ostree rollback
+Moving '080cf9c61a5e38f8101290db5025a71fc6cfb189a9393785ba347d006d6285ee.0' to be first deployment
+Transaction complete; bootconfig swap: yes deployment count change: 0
+Downgraded:
+  glibc 2.25-8.fc26 -> 2.25-7.fc26
+  glibc-all-langpacks 2.25-8.fc26 -> 2.25-7.fc26
+  glibc-common 2.25-8.fc26 -> 2.25-7.fc26
+  krb5-libs 1.15.1-22.fc26 -> 1.15.1-21.fc26
+  libcrypt-nss 2.25-8.fc26 -> 2.25-7.fc26
+  python2-setuptools 36.2.0-2.fc26 -> 36.2.0-1.fc26
+  python3 3.6.2-5.fc26 -> 3.6.2-1.fc26
+  python3-libs 3.6.2-5.fc26 -> 3.6.2-1.fc26
+  python3-setuptools 36.2.0-2.fc26 -> 36.2.0-1.fc26
+  system-python 3.6.2-5.fc26 -> 3.6.2-1.fc26
+  system-python-libs 3.6.2-5.fc26 -> 3.6.2-1.fc26
+  tmux 2.5-4.fc26 -> 2.5-1.fc26
+Run "systemctl reboot" to start a reboot
+....
+
+=== `rpm-ostree deploy <version>`
+
+The `rpm-ostree deploy` command makes use of the server-side history
+feature of OSTree. It will search the history of the current branch for
+a commit with the specified version, and deploy it.  This can be used
+in scripts to ensure consistent updates.  For example, if the upstream
+OS vendor provides an update online, you might not want to deploy it until
+you've tested it.  This helps ensure that when you upgrade, you are
+getting exactly what you asked for.
+
+You can see the some example output of a deploy on a Fedora 26 Atomic Host:
+
+....
+# rpm-ostree deploy 26.109
+Resolving version '26.109'
+1 metadata, 0 content objects fetched; 569 B transferred in 3 seconds
+
+138 metadata, 2011 content objects fetched; 114566 KiB transferred in 672 seconds
+Copying /etc changes: 24 modified, 0 removed, 55 added
+Transaction complete; bootconfig swap: yes deployment count change: 1
+Freed objects: 2.3 kB
+Downgraded:
+  glibc 2.25-8.fc26 -> 2.25-7.fc26
+  glibc-all-langpacks 2.25-8.fc26 -> 2.25-7.fc26
+  glibc-common 2.25-8.fc26 -> 2.25-7.fc26
+  krb5-libs 1.15.1-22.fc26 -> 1.15.1-21.fc26
+  libcrypt-nss 2.25-8.fc26 -> 2.25-7.fc26
+  python2-setuptools 36.2.0-2.fc26 -> 36.2.0-1.fc26
+  python3 3.6.2-5.fc26 -> 3.6.2-1.fc26
+  python3-libs 3.6.2-5.fc26 -> 3.6.2-1.fc26
+  python3-setuptools 36.2.0-2.fc26 -> 36.2.0-1.fc26
+  system-python 3.6.2-5.fc26 -> 3.6.2-1.fc26
+  system-python-libs 3.6.2-5.fc26 -> 3.6.2-1.fc26
+  tmux 2.5-4.fc26 -> 2.5-1.fc26
+Run "systemctl reboot" to start a reboot
+....
+
+== Hybrid image/packaging via package layering
+
+It is possible to dynamically add more packages onto the system that are not
+part of the commit composed on the server. These additional "layered" packages
+are persistent across upgrades, rebases, and deploys (contrast with the
+link:https://github.com/ostreedev/ostree/blob/master/man/ostree-admin-unlock.xml[ostree unlocking]
+mechanism).
+
+This is where the true hybrid image/package nature of `rpm-ostree` comes into
+play; you get a combination of the benefits of images and packages.  The
+package updates are still fully transactional and offline.
+
+For example, you can use package layering to install 3rd party
+kernel modules, or userspace driver daemons such as `pcsc-lite-ccid`.
+While most software should go into a container, you have full flexibilty
+to use packages where it suits.
+
+
+=== `rpm-ostree install/uninstall <pkg>`
+
+The `rpm-ostree install` command will download the target package, its dependencies,
+and create a new deployment with those packages installed.  Additionally, you can use
+the `rpm-ostree install` to layer local RPMs onto the system.  To remove layered
+packages, use `rpm-ostree uninstall`.
+
+By default, every `rpm-ostree` operation is "offline" - it has no effect
+on your running system, and will only take effect when you reboot.  This
+"pending" state is called the "pending deployment".  Operations can be chained;
+for example, if you invoke `rpm-ostree upgrade` after installing a package, your
+new root will upgraded with the package also installed.
+
+
+== Rebasing via `rpm-ostree rebase`
+
+Your operating system vendor may provide multiple base branches.  For example,
+Fedora Atomic Host has branches of the form:
+
+ - `fedora/26/x86_64/atomic-host`
+ - `fedora/26/x86_64/updates/atomic-host`
+ - `fedora/27/x86_64/atomic-host`
+
+You can use the `rebase` command to switch between these; this can represent a
+major version upgrade, or logically switching between different "testing"
+streams within the same release. Like every other `rpm-ostree` operation, All
+layered packages and local state will be carried across.
+
+The `rebase` command also allows you to switch your system to an entirely new
+OS distribution.  This means it is possible to switch your Fedora 26 Atomic Host
+to a version of CentOS Atomic Host.  While this is not likely to be done on a
+production system, it can be useful in certain testing scenrios.
+
+
+== Other local state changes
+
+=== `rpm-ostree cleanup`
+
+The `rpm-ostree cleanup` command allows the user to remove data generated by
+`rpm-ostree` operations which is no longer used.  This includes non-booted
+deployments, cached RPM repodata, partially downloaded RPMs, or transient
+allocated data as result of interrupted operations.
+
+The `-b` flag will remove the data remaining from interrupted operations.
+If you want to free up space on your system, use this options first.
+
+The `-m` flag will remove the cached RPM repodata and partially downloaded
+RPMs.
+
+The `-p` flag will remove the pending deployment (usually as a result of an
+upgrade or an install operation).
+
+The `-r` flag will remove the rollback deployment.
+
+You can combine all the flags in a single operation to cleanup all the data
+that can be cleaned up.
+
+
+=== `rpm-ostree initramfs`
+
+The `rpm-ostree intitramfs` command is primarily used to enable the regeneration
+of the initramfs after its configuration has changed or a kernel driver has been added.
+
+You can query the state of initramfs regeneration by using the command without any
+options.
+
+Or you can enable/disable the regeneration by using the `--enable` or `--disable`
+options respectively.
+
+=== `rpm-ostree reload`
+
+
+== Querying the RPM database
+
+=== `rpm-ostree db diff`
+
+=== `rpm-ostree db list`
+
+=== `rpm-ostree db version`
+
+
+== Composing an ostree commit
+
+=== `rpm-ostree compose tree`
+
+
+== Experimental interface
+
+There is a generic `rpm-ostree ex` command that offers experimental features.
+
+=== `rpm-ostree ex container`
+
+=== `rpm-ostree ex livefs`
+
+=== `rpm-ostree ex override`
+
+=== `rpm-ostree ex unpack`