Chapter 6. Managing Atomic Hosts

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>

Use the --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

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:

# rpm-ostree -m
# rpm-ostree -b

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.

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.

# rpm-ostree install <package>

# rpm-ostree uninstall <package>

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.

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:

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 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.