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. 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. 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 state. You can use the -r option to initiate a reboot immediately: 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. Use the --preview option to check the package difference between the specified version and your currently running tree. 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: You can delete an ostree deployment using one of the following commands: The -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: The -m option deletes cached RPM repository metadata, while -b clears temporary files, but leaves deployments intact. Both the atomic and ostree tools have built-in detailed --help options, to check all commands available on the system, use atomic host --help or ostree --help . 6.2. Package Layering Using 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: To remove a layered package, use the following command: Running the 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 livefs command. If you are deleting or upgrading the packages, use the rpm-ostree ex livefs --replace command. 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: Install the strace package as follows: Check the status again to see the layered package created by installing strace. Note that the strace package does not appear to be installed yet: 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 install several times consecutively without rebooting or applying changes live, only the most recent command will take effect. If you install wget and strace consecutively and reboot afterwards, only strace will be present after reboot. To add multiple packages onto a new deployment, specify them all on the same line with the command. For example: Installing packages which contain files owned by users other than root is currently not supported. For example, the httpd package contains files with a group ownership of apache , installing it will fail: After rpm-ostree install , do not use atomic host deploy or rpm-ostree deploy to 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 upgrade or rpm-ostree upgrade to upgrade to the release. However, atomic host rollback or rpm-ostree rollback will still be successful and bring the system back to the 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: Check again to see that the strace package is installed and note the status of deployments, including the new LiveCommit: 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 The --download-only and --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 The 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. Run the rpm-ostree override command. Reboot the Atomic host for the change to take effect. Note 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: Reboot the Atomic Host system: Check that the packages have been installed and are available: If you just want to go back to the 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 rsyslog , 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 etcd and flannel . For detailed information, see Running System Containers chapter from the Red Hat Enterprise Linux Atomic Host Managing Containers Guide.

Commands:
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
atomic host upgrade systemctl reboot
atomic host rollback -r
atomic host deploy <version/commit ID>
atomic host deploy 7.3 --preview
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
rpm-ostree cleanup -r rpm-ostree cleanup -p
rpm-ostree -m rpm-ostree -b
rpm-ostree install <package>
rpm-ostree uninstall <package>
-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. <security@redhat.com>"
-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
-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
rpm -q strace package strace is not installed
rpm-ostree install wget strace
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 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
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
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
systemctl reboot
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