keremet/rpm-ostree
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs: Update admin handbook, mention ex in manpage

Browse Source 
- Focus on `rpm-ostree` rather than `atomic host` since...well, a
   lot of stuff isn't exposed there and the whole branding is confusing.
 - Mention `ex`, `rebase` etc.

Closes: #908
Approved by: miabbott
This commit is contained in:
Colin Walters 2017-08-03 06:41:18 -07:00 committed by Atomic Bot
parent 9b22c2c516
commit a3250f221d
2 changed files with 79 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
docs/manual/administrator-handbook.md
View File

@ -4,31 +4,36 @@ 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 an `rpm-ostree` based system. Also remember that in a Project Atomic
system, the `atomic host` command (from the system, the `atomic host` command (from the
[Atomic command](https://github.com/projectatomic/atomic/)) is an [Atomic command](https://github.com/projectatomic/atomic/)) is an
alias for `rpm-ostree`. The author tends to use the former on client alias for `rpm-ostree`.
systems, and the latter on compose servers.
``` ```
# atomic host status # rpm-ostree status
``` ```
Will show you your deployments, in the order in which they will appear Will show you your deployments, in the order in which they will appear
in the bootloader. The `*` shows the currently booted deployment. in the bootloader. The `●` shows the currently booted deployment.
``` ```
# atomic host upgrade # rpm-ostree upgrade
``` ```
Will perform a system upgrade, creating a *new* chroot, and set it as
the default for the next boot. You should use `systemctl reboot` 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. shortly afterwards.
``` ```
# atomic host rollback # rpm-ostree rollback
``` ```
By default, the `atomic upgrade` will keep at most two bootable
"deployments", though the underlying technology supports more. This rolls back to the previous state. By default, the `rpm-ostree upgrade` will
keep at most two bootable "deployments", though the underlying technology
supports more.
``` ```
# atomic host deploy <version> # rpm-ostree deploy <version>
``` ```
This command makes use of the server-side history feature of OSTree. This 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 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 specified version, and deploy it. This can be used in scripts to
@ -37,33 +42,66 @@ 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 you've tested it. This helps ensure that when you upgrade, you are
getting exactly what you asked for. getting exactly what you asked for.
## Package layering ### Hybrid image/packaging via package layering
It is possible to add more packages onto the system that are not part of It is possible to dynamically add more packages onto the system that are not
the commit composed on the server. These additional "layered" packages part of the commit composed on the server. These additional "layered" packages
are persistent across upgrades, rebases, and deploys (contrast with the are persistent across upgrades, rebases, and deploys (contrast with the
ostree [unlocking](https://github.com/ostreedev/ostree/blob/master/man/ostree-admin-unlock.xml) ostree [unlocking](https://github.com/ostreedev/ostree/blob/master/man/ostree-admin-unlock.xml) mechanism).
mechanism). This allows you to easily enhance the base set of packages
on only some machines, or only temporarily (rather than asking to have This is where the true hybrid image/package nature of rpm-ostree comes into
it part of the server compose and affecting every machine). For example, play; you get a combination of the benefits of images and packages. The
you may wish to permanently install some diagnostics tools on a test package updates are still fully transactional and offline.
machine.
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 pkg-add <pkg> # rpm-ostree install <pkg>
``` ```
Will download the target package, its dependencies, and create a new Will download the target package, its dependencies, and create a new deployment
deployment with those packages installed. with those packages installed. 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
``` ```
# rpm-ostree pkg-remove <pkg> rpm-ostree rebase -b $branchname
``` ```
Will create a new deployment with the target package removed. Your operating system vendor may provide multiple base branches. For example,
Fedora Atomic Host has branches of the form:
Note that package layering is currently in preview mode and as such may - `fedora/26/x86_64/atomic-host`
change interface or functionality before being declared stable. - `fedora/26/x86_64/updates-testing/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.
### Other local state changes
See `man rpm-ostree` for more. For example, there is an `rpm-ostree initramfs`
command that enables local initramfs generation.
### Experimental interface
There is a generic `rpm-ostree ex` command that offers experimental features.
One of those is `rpm-ostree ex livefs`, which offers the ability to apply
changes from the pending deployment to the booted deployment.
See `man rpm-ostree` for more information.
## Filesystem layout ## Filesystem layout

14
man/rpm-ostree.xml
View File

@ -415,6 +415,20 @@ Boston, MA 02111-1307, USA.
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><command>ex</command></term>
<listitem>
<para>
This command offers access to experimental features; command line
stability is not guaranteed. The available subcommands will be listed
by invoking <command>rpm-ostree ex</command>. For example, there is
<command>rpm-ostree ex livefs</command> which is an experimental
interface for applying changes to the booted deployment.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</refsect1> </refsect1>