Chapter 6. Managing Atomic Hosts
6.1. Atomic Host
The atomic command-line tool can be used to check the status of your Atomic Host system, perform upgrades and rollbacks or deploy a specific operating system tree.
Use atomic host status to list the operating system trees downloaded on your system and check which version you are currently running. The asterisk (
*) marks the currently running tree.
# atomic host status State: idle Deployments: * rhel-atomic-host-ostree:rhel-atomic-host/7/x86_64/standard Version: 7.3 (2016-09-27 17:53:07) BaseCommit: d3fa3283db8c5ee656f78dcfc0fcffe6cd5aa06596dac6ec5e436352208a59cb Commit: f5e639ce8186386d74e2558e6a34f55a427d8f59412d47a907793e046875d8dd OSName: rhel-atomic-host rhel-atomic-host-ostree:rhel-atomic-host/7.2/x86_64/standard Version: 7.2.7 (2016-09-15 22:28:54) BaseCommit: dbbc8e805f0003d8e55658dc220f1fe1397caf80221cc050eeb1bbf44bef56a1 Commit: 5cd426fa86bd1652ecd8f7d489f89f13ecb7d36e66003b0d7669721cb79545a8 OSName: rhel-atomic-host
To upgrade your system, use atomic host upgrade. This command will download the latest ostree available and will deploy it after you reboot the system. When you upgrade again, the newly downloaded ostree will replace the oldest one. Upgrading can take a few minutes.
# atomic host upgrade # systemctl reboot
To switch back to the other downloaded tree on your system, use atomic host rollback. This command is particularly useful when there is a problem after upgrade (for example the new packages break a service that you’ve configured) because it lets you quickly switch back to the previous state. You can use the
-r option to initiate a reboot immediately:
# atomic host rollback -r
To deploy a specific version of an ostree, use atomic host deploy. You can specify a version or a commit ID if you know it.
# atomic host deploy <version/commit ID>
--preview option to check the package difference between the specified version and your currently running tree.
# atomic host deploy 7.3 --preview
For finer tasks you can use the ostree tool to manage you Atomic Host. For example, if you are unsure about the version numbering of the trees, you can use the following commands to fetch the ostree logs and list the versions available:
# ostree pull --commit-metadata-only --depth -1 rhel-atomic-host-ostree:rhel-atomic-host/7/x86_64/standard # ostree log rhel-atomic-host/7/x86_64/standard
You can delete an ostree deployment using one of the following commands:
# rpm-ostree cleanup -r # rpm-ostree cleanup -p
-p option causes the pending deployment to be removed, while
-r removes the rollback deployment.
To clear temporary files and cached data, use one of the following commands:
# rpm-ostree -m # rpm-ostree -b
-m option deletes cached RPM repository metadata, while
-b clears temporary files, but leaves deployments intact.
ostree tools have built-in detailed
--help options, to check all commands available on the system, use
atomic host --help or
6.2. Package Layering
rpm-ostree install, you can add an RPM software packages that is not part of the original OSTree permanently to the system. With
rpm-ostree override, you can override an existing RPM package in the base system layer with a different version of that package. These features are done using the package layering feature.
Package layering is useful when you need to install a certain package on a single machine, without affecting other machines that share the same OSTree. An example use case of package layering is installing diagnostics tools, such as
strace. An example of overriding a package in the base system is if you wanted to use a different version of the docker package.
6.2.1. Installing a new RPM package on a RHEL Atomic Host
To install a layered package and its dependencies on RHEL Atomic Host, run the following command:
# rpm-ostree install <package>
To remove a layered package, use the following command:
# rpm-ostree uninstall <package>
rpm-ostree install or
rpm-ostree uninstall does not immediately install or uninstall the packages. To actually install or uninstall the packages, you have two options:
- Reboot the system.
Use LiveFS to apply the changes immediately.Note
LiveFS is still a technology preview feature, so do not rely on it in production.
If you are only installing packages, use the
rpm-ostree ex livefscommand.
If you are deleting or upgrading the packages, use the
rpm-ostree ex livefs --replacecommand.
You can find out which packages have been manually installed on the system by running
atomic host status.
The following is an example of installing
strace on RHEL Atomic Host and how to verify it is part of the OSTree. Just as with installing a package with
yum, you must register and subscribe your Atomic Host system before installing packages:
Check the current status of your Atomic Host’s deployments:
-bash-4.2# rpm-ostree status State: idle Deployments: ● rhelah-7.4:rhel-atomic-host/7/x86_64/standard Version: 7.4.0 (2017-07-28 00:26:01) Commit: 846fb0e18e65bd9a62fc9d952627413c6467c33c2d726449a1d7ad7690bbb93a rhel-atomic-host-ostree:rhel-atomic-host/7/x86_64/standard Version: 7.4.0 (2017-07-13 17:46:26) Commit: c28cad0d4144d91a3c206574e9341cd5bdf7d34cfaa2acb74dd84c0bf022593a GPGSignature: 1 signature Signature made Thu 13 Jul 2017 01:54:13 PM EDT using RSA key ID 199E2F91FD431D51 Good signature from "Red Hat, Inc. <firstname.lastname@example.org>"
Install the strace package as follows:
-bash-4.2# rpm-ostree install strace Checking out tree 846fb0e... done ... Importing metadata [===========================================] 100% Resolving dependencies... done Will download: 1 package (470.0 kB) Downloading from rhel-7-server-rpms: [=======================] 100% Importing: [===================================================] 100% Overlaying... done Writing rpmdb... done Writing OSTree commit... done Copying /etc changes: 20 modified, 5 removed, 43 added Transaction complete; bootconfig swap: yes deployment count change: 0 Freed objects: 388.5 MB Added: strace-4.12-4.el7.x86_64 Run "systemctl reboot" to start a reboot
Check the status again to see the layered package created by installing strace.
-bash-4.2# rpm-ostree status State: idle Deployments: rhelah-7.4:rhel-atomic-host/7/x86_64/standard Version: 7.4.0 (2017-07-28 00:26:01) BaseCommit: 846fb0e18e65bd9a62fc9d952627413c6467c33c2d726449a1d7ad7690bbb93a LayeredPackages: strace ● rhelah-7.4:rhel-atomic-host/7/x86_64/standard Version: 7.4.0 (2017-07-28 00:26:01) Commit: 846fb0e18e65bd9a62fc9d952627413c6467c33c2d726449a1d7ad7690bbb93a
Note that the strace package does not appear to be installed yet:
# rpm -q strace package strace is not installed
Consider several issues: Although the package was installed on its own layer, it does not yet appear as being installed on the system. At this point you need to apply the pending deployment by either rebooting or applying them immediately using
rpm-ostree ex livefs. Before making that decision, however, take into account these notes and limitations:
If you run
rpm-ostree installseveral times consecutively without rebooting or applying changes live, only the most recent command will take effect. If you install
straceconsecutively and reboot afterwards, only
stracewill be present after reboot. To add multiple packages onto a new deployment, specify them all on the same line with the command. For example:
# rpm-ostree install wget strace
Installing packages which contain files owned by users other than root is currently not supported. For example, the
httpdpackage contains files with a group ownership of
apache, installing it will fail:
# rpm-ostree install httpd notice: pkg-add is a preview command and subject to change. Downloading metadata: [====================] 100% Resolving dependencies... done error: Unpacking httpd-2.4.6-40.el7_2.4.x86_64: Non-root ownership currently unsupported: path "/run/httpd" marked as root:apache)
rpm-ostree install, do not use
atomic host deployor
rpm-ostree deployto deploy a specific version OSTree version older than 7.2.6. If you attempt to deploy to such a version after
rpm-ostree install, the system will be left in a state where you will be unable to use
atomic host upgradeor
rpm-ostree upgradeto upgrade to the next release. However,
atomic host rollbackor
rpm-ostree rollbackwill still be successful and bring the system back to the previous deployment.
Reboot or LiveFS: Either reboot for the deployments to take effect or use the livefs feature, to have them immediately take effect, as follows:
# rpm-ostree ex livefs notice: "livefs" is an experimental command and subject to change. Diff Analysis: 846fb0e18e65bd9a62fc9d952627413c6467c33c2d726449a1d7ad7690bbb93a => 97f937f3789d0f25b887bcd4fcc03d33b76ee4c87095af48c602b5826519ce1b Files: modified: 0 removed: 0 added: 11 Packages: modified: 0 removed: 0 added: 1 Preparing new rollback matching currently booted deployment Copying /etc changes: 20 modified, 5 removed, 43 added Transaction complete; bootconfig swap: yes deployment count change: 1 Overlaying /usr... done
Check again to see that the strace package is installed and note the status of deployments, including the new LiveCommit:
# rpm -q strace strace-4.12-4.el7.x86_64 # rpm-ostree status State: idle Deployments: rhelah-7.4:rhel-atomic-host/7/x86_64/standard Version: 7.4.0 (2017-07-28 00:26:01) BaseCommit: 846fb0e18e65bd9a62fc9d952627413c6467c33c2d726449a1d7ad7690bbb93a Commit: 97f937f3789d0f25b887bcd4fcc03d33b76ee4c87095af48c602b5826519ce1b LayeredPackages: strace ● rhelah-7.4:rhel-atomic-host/7/x86_64/standard Version: 7.4.0 (2017-07-28 00:26:01) BootedCommit: 846fb0e18e65bd9a62fc9d952627413c6467c33c2d726449a1d7ad7690bbb93a LiveCommit: 97f937f3789d0f25b887bcd4fcc03d33b76ee4c87095af48c602b5826519ce1b rhelah-7.4:rhel-atomic-host/7/x86_64/standard Version: 7.4.0 (2017-07-28 00:26:01) Commit: 846fb0e18e65bd9a62fc9d952627413c6467c33c2d726449a1d7ad7690bbb93a
At this point, you can go ahead and start using the installed software. For more information on rpm-ostree and Live updates, see the Project Atomic rpm-ostree
6.2.2. Downloading and caching RPMs for later installation
--cache-only options allow to separate the
rpm-ostree install process into two stages:
- Downloading and caching the layered RPMs.
- Installing from the cached data.
These options enable you to download the RPMs at one time, and then install them later whenever you choose, even offline.
6.2.3. Updating the repository metadata
rpm-ostree refresh-md subcommand downloads and caches the latest repository metadata. It is similar to the
yum makecache command for the Yum package manager.
6.2.4. Overriding an existing RPM package
To override an RPM package that is in the Atomic base and install a different version, you use the
rpm-ostree override command. Here’s how it works:
- Copy the RPM package you want to use to the Atomic host. Include any dependent packages needed by the RPM as well. The packages can be upgrades or downgrades from the current packages.
- Reboot the Atomic host for the change to take effect.
See Locking the version of the docker package on RHEL Atomic Host for an example of how to use
rpm-ostree override to replace the docker runtime in Atomic.
Here’s an example of replacing the openssh-server package (and dependent packages) on a RHEL Atomic Host.
- Get the RPM package (and dependent packages) you want to replace and put them in a directory on the Atomic Host.
With the packages in the current directory (in this case, downgrades of openssh-server, openssh-clients, and openssh), type the following to replace those packages:
# rpm-ostree override replace \ openssh-server-6.6.1p1-35.el7_3.x86_64.rpm \ openssh-clients-6.6.1p1-35.el7_3.x86_64.rpm \ openssh-6.6.1p1-35.el7_3.x86_64.rpm Checking out tree 5df677d... done ... Transaction complete; bootconfig swap: yes deployment count change: 1 Downgraded: openssh 7.4p1-16.el7 -> 6.6.1p1-35.el7_3 openssh-clients 7.4p1-16.el7 -> 6.6.1p1-35.el7_3 openssh-server 7.4p1-16.el7 -> 6.6.1p1-35.el7_3 Run "systemctl reboot" to start a reboot
Reboot the Atomic Host system:
# systemctl reboot
Check that the packages have been installed and are available:
# atomic host status State: idle Deployments: ● ostree://rhel-atomic-host-ostree:rhel-atomic-host/7/x86_64/standard Version: 7.5.0 (2018-04-05 10:29:00) BaseCommit: 5df677dcfef08a87dd0ace55790e184a35716cf11260239216bfeba2eb7c60b0 ReplacedBasePackages: openssh openssh-server openssh-clients 7.4p1-16.el7 -> 6.6.1p1-35.el7_3 # rpm -q openssh openssh-clients openssh-server openssh-6.6.1p1-35.el7_3.x86_64 openssh-clients-6.6.1p1-35.el7_3.x86_64 openssh-server-6.6.1p1-35.el7_3.x86_64
If you just want to go back to the previous package versions, you can use
rpm-ostree override reset to do that. Use
rpm-ostree override reset <packagename> to remove individual packages or
rpm-ostree override reset --all to remove all overridden packages.
6.3. "ostree admin unlock"
ostree admin unlock unlocks the current ostree deployment and allows packages to be installed temporarily by mounting a writable overlayfs on /usr. However, the packages installed afterwards will not persist after reboot.
ostree admin unlock also has certain limitations and known issues with overlayfs and SELinux, so it should be used only for testing. For adding software,
rpm-ostree install is recommended for long-term use.
6.4. System Containers and Super-Privileged Containers (SPCs)
In some cases, containerized services or applications require that they are run from a container image that is built in a different than the default way for Docker-formatted containers. Such special case containers are the Super-Privileged Containers (SPCs), and the system containers. They are necessary in two situations:
- SPCs: When a certain container needs more privileges and access to the host.
Super-Privileged Containers are run with special privileges to the host computer, and unlike the default Docker-formatted containers, are able to modify the host. Tools for monitoring and logging are containzerized in SPCs so they can have the access to the host they requires. Such SPCs are
sadc, and the
atomic-tools container. For detailed information about SPCs, see Running Super-Privileged Containers chapter from the Red Hat Enterprise Linux Atomic Host Managing Containers Guide.
- System Containers: A certain container needs to run independently of the docker daemon.
System containers are a way to containerize services which are needed before the docker daemon is running. Such services configure the environment for docker, (for example setting up networking), so they can’t be run by the docker daemon and because of that, they are not Docker-formatted images. They use
runc for runtime,
ostree for storage,
skopeo for searching and pulling from a registry and systemd for management. A system container is executed from a systemd UNIT file using the
runc utility. Additionally, containerizing such services is a way to make the ostree system image smaller. Such System Containers are
flannel. For detailed information, see Running System Containers chapter from the Red Hat Enterprise Linux Atomic Host Managing Containers Guide.