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>

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.

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:

# rpm-ostree install <package>

To remove a layered package, use the following command:

# rpm-ostree uninstall <package>

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:

  1. 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. <security@redhat.com>"
  2. 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
  3. 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
  4. Note that the strace package does not appear to be installed yet:

    # rpm -q strace
    package strace is not installed
  5. 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:

      # rpm-ostree install wget strace
    • 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:

      # 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)
    • 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 next release. However, atomic host rollback or rpm-ostree rollback will still be successful and bring the system back to the previous deployment.
  6. 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
  7. 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

The --download-only and --cache-only options allow to separate the rpm-ostree install process into two stages:

  1. Downloading and caching the layered RPMs.
  2. 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.

  1. Get the RPM package (and dependent packages) you want to replace and put them in a directory on the Atomic Host.
  2. 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
  3. Reboot the Atomic Host system:

    # systemctl reboot
  4. 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 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.