Getting Started with Red Hat Enterprise Linux Atomic Host

Updated -

Red Hat Enterprise Linux Atomic Host provides a way to host Linux containers in a minimal version of Red Hat Enterprise Linux. This guide explains how to acquire, install, register, update, configure, upgrade, and run Red Hat Enterprise Linux Atomic Host. This guide also explains how to install applications on Red Hat Enterprise Linux Atomic Host.

Table of Contents

Overview

This document, the Atomic Quickstart Guide, explains how to set up Red Hat Enterprise Linux Atomic Host.

Red Hat Enterprise Linux Atomic host is a variation of Red Hat Enterprise Linux 7 optimized to run Linux containers in the Docker format. It has been designed to take advantage of the powerful technology available in Red Hat Enterprise Linux 7. Red Hat Enterprise Linux Atomic Host uses SELinux to provide strong safeguards in multi-tenant environments, and provides the ability to perform atomic upgrades and rollbacks, enabling quicker and easier maintenance with less downtime. Red Hat Enterprise Linux Atomic Host uses the same upstream projects delivered via the same RPM packaging as Red Hat Enterprise Linux 7.

Red Hat Enterprise Linux Atomic Host is pre-installed with the following tools to support Linux containers:

Red Hat Enterprise Linux Atomic Host makes use of the following technologies:

  • OSTree and rpm-OSTree - These projects provide atomic upgrades and the ability to roll back upgrades.
  • systemd - The powerful new init system for Linux systems that enables faster boot times and easier system orchestration.
  • SELinux - Enabled by default to provide complete multi-tenant security. You'll also find Integrity Measurement Architecture (IMA), audit and libwrap available from systemd.

IMPORTANT: Red Hat Enterprise Linux Atomic Host is not managed in the same way that other Red Hat Enterprise Linux 7 variants are managed. Specifically:

  • You do not use yum to upgrade the system. For more information, see Installing Applications on Red Hat Enterprise Linux Atomic Host.
  • There are only two writable directories for local system configuration: /etc/ and /var/. The /usr/ directory is mounted read-only. Other directories are symlinks to a writable location. For example, the /home/ directory is a symlink to the /var/home/ directory. For more information, see Red Hat Enterprise Linux Atomic Host File System.
  • The default partitioning dedicates most of the available space for the containers, using direct LVM instead of the default loopback.

User and Host specific data should be stored only in the /var/ directory. Only configuration files in the /etc/ directory should be modified. For more information, see Red Hat Enterprise Linux Atomic Host File System.

Red Hat Enterprise Linux Atomic Host File System

Red Hat Enterprise Linux Atomic Host uses rpm-OSTree (also called atomic), an open source tool, to manage bootable, immutable, versioned file system trees made of RPM content. These trees are currently composed by Red Hat, from packages. The rpm-ostree tool replicates the trees atomically. This results in a strategy for upgrade and maintenance that centers around atomic updates. The use of rpm-ostree instead of yum to upgrade and maintain software means that Red Hat Enterprise Linux Atomic Host is managed differently than other Red Hat Enterprise Linux 7 variants.

Specifically, when using Red Hat Enterprise Linux Atomic Host, the operating system content is mounted in a read-only manner. Updates work in the following way: a new bootable file system tree is generated, which shares storage with the current bootable file system tree. The old file system tree is retained in parallel with the new file system tree. This means that the first, pre-upgrade, version of the file system tree can be atomically restored as the running version if, for some reason, the second, post-upgrade version is somehow less desirable than the first.

User files that are intended to persist across upgrades, including containers and data, should be placed in the /var/ directory. The operating system itself is stored in the /usr/ directory and is read-only. If you perform a long file listing in the root directory using the command ls -l /, you will discover that many of the traditional root-level directories are symbolic links to one of these two locations. For example, the /home/ directory is a symbolic link to the /var/home/ directory. This directory will therefore persist across upgrades.

There are two new directories in the root (/) directory: the /sysroot/ directory, and the /ostree/ directory. For more information on these directories, see Understanding atomic upgrades in Red Hat Enterprise Linux Atomic Host.

Getting and Installing Red Hat Enterprise Linux Atomic Host

Red Hat Enterprise Linux Atomic Host is distributed in multiple formats and able to be installed on bare-metal, in multiple virtual environments and in public and private cloud infrastructures. You can find the installation media on the Red Hat Enterprise Linux Atomic Host Product Page when you click the Download button under Installation Media. Complete installation instructions can be found in the Red Hat Enterprise Linux Installation Guide.

System Requirements

Red Hat Enterprise Linux Atomic Host should be compatible with most hardware in systems that were factory built within the last two years. Hardware compatibility is a particularly important concern if you have an older or custom-built system. Because hardware specifications change almost daily, it is recommended that all systems be checked for compatibility. The most recent list of supported hardware can be found in the Red Hat Hardware Compatibility List. Also see Red Hat Enterprise Linux technology capabilities and limits for general information about system requirements.

Red Hat Enterprise Linux Atomic Host has the same runtime requirements as Red Hat Enterprise Linux. However, for Anaconda based installation (interactive, Kickstart, and PXE) on bare metal or in virtual environments, 2GB of memory is required.

Registering Red Hat Enterprise Linux Atomic Host

To enable software updates, you must register your Red Hat Enterprise Linux Atomic Host installation. This is done with the subscription-manager command as described below. If your system is located on a network that requires the use of an HTTP proxy, please see the Red Hat Knowledge Base Article on configuring subscription manager to use an HTTP proxy. The --name= option may be included if you wish to provide an easy to remember name to be used when reviewing subscription records.

$ sudo subscription-manager register --username=<username> --auto-attach

Note: Red Hat Enterprise Linux Atomic Host works only with Red Hat Subscription Manager (RHSM). Red Hat Enterprise Linux Atomic Host does not work with RHN.

Note: Red Hat Enterprise Linux Atomic Host registers two product IDs. The first is Product ID 271, Red Hat Enterprise Linux Atomic Host. The second is Product ID 69, Red Hat Enterprise Linux Server. They both use the same entitlement.

A properly registered system will display both IDs as is shown below:

~~~
$ sudo subscription-manager list
+-------------------------------------------+
    Installed Product Status
+-------------------------------------------+
Product Name:   Red Hat Enterprise Linux Atomic Host
Product ID:     271 
Version:        7
Arch:           x86_64
Status:         Subscribed
Status Details: 
Starts:         02/27/2015
Ends:           02/26/2016

Product Name:   Red Hat Enterprise Linux Server
Product ID:     69
Version:        7.1
Arch:           x86_64
Status:         Subscribed
Status Details: 
Starts:         02/27/2015
Ends:           02/26/2016

~~~

Additional information about using subscription-manager in situations where a specific subscription pool must be used can be found in the known issues section. The subscription-manager command is also documented in section 3.2. Registering from the Command Line of the Red Hat Subscription Management guide. An explanation of how containers inherit the repositories of the systems hosting them is available in the KBase article How do Docker containers use Red Hat subscriptions or entitlements to access repositories?.

Configuring Red Hat Enterprise Linux Atomic Host

Red Hat Enterprise Linux Atomic Host is configured in a manner similar to Red Hat Enterprise Linux 7, using the configuration files in the /etc/ directory. Red Hat Enterprise Linux Atomic Host is a minimal server product without a desktop. This means that the graphical configuration tools found in the GUI are not available.

Currently, some system users that in Red Hat Enterprise Linux 7 would be listed in the /etc/passwd file have been relocated into the read-only /usr/lib/passwd file. Because applications on Red Hat Enterprise Linux Atomic Host are run inside of Linux containers, this will not affect deployment. The traditional user management tools, such as useradd, will write locally added users to the /etc/passwd file as expected.

If you did not configure networking during the installation you may configure it post-installation using the nmcli tool. The following commands create a network connection called atomic, set up a host name and then activate that connection.

    # nmcli con add type ethernet con-name atomic ifname eth0
    # nmcli con modify my-office my-office ipv4.dhcp-hostname atomic ipv6.dhcp-hostname atomic
    # nmcli con up atomic

For more details on how to use the nmcli tool, see Section 2.3.2. Connecting to a Network Using nmcli in the Red Hat Enterprise Linux 7 Networking Guide.

For more information on configuring Red Hat Enterprise Linux 7, see the Red Hat Enterprise Linux 7 System Administrator's Guide.

Upgrading and Reverting Red Hat Enterprise Linux Atomic Host

Red Hat Enterprise Linux Atomic Host uses rpm-OSTree, an open source tool, to manage bootable, immutable, versioned file system trees made of RPM content. In comparison to other variants of Red Hat Enterprise Linux 7 which use yum and have a traditional package management model, Red Hat Enterprise Linux Atomic Host uses OSTree and is upgraded by preparing a new operating system root, and making it the default for the next boot.

To perform an upgrade, execute the following commands:

$ sudo atomic host upgrade
$ sudo systemctl reboot

If you are using a system that requires an HTTP proxy, the proxy is configured with an environment variable. To configure the environment variable, use a command similar to the following one:

$ sudo env http_proxy=http://proxy.example.com:port/ atomic host upgrade

To revert to a previous installation of Red Hat Enterprise Linux Atomic Host, execute the following commands:

$ sudo atomic host rollback
$ sudo systemctl reboot

Two versions of Red Hat Enterprise Linux Atomic Host are available on the system after the initial upgrade. One is the currently running version. The other is either a new version recently installed from an upgrade or the version that was in place prior to the last upgrade.

Important: Configuration is preserved across updates, but is only forward-preserved. This means that if you make a configuration change and then later roll back to a previous version, the configuration change you made is reverted.

Note: Running the atomic host upgrade command will replace the non-running version of Red Hat Enterprise Linux Atomic Host. This version will also be configured to be used during the next boot.

To determine which version of the operating system is running, execute the following command.

$ sudo atomic host status

The output that includes the hash name of the directory in the /ostree/deploy/rhel-atomic-host/ directory looks like this:

$ sudo atomic host status
  TIMESTAMP (UTC)         VERSION   ID             OSNAME               REFSPEC                                                 
* 2015-05-07 19:00:48     7.1.2     203dd666d3     rhel-atomic-host     rhel-atomic-host:rhel-atomic-host/7/x86_64/standard     
  2015-04-02 20:14:06     7.1.1-1   21bd99f9f3     rhel-atomic-host     rhel-atomic-host:rhel-atomic-host/7/x86_64/standard     

This fictional sample output shows that version 7.1.0 will be booted into on the next restart. The version to be booted on the next restart is printed first.

This fictional sample also shows that version 7.0.9 is the currently running version. The currently running version is marked with an asterisk (*). This output was created just after the atomic host upgrade command was executed, and that means that a new version has been staged to be applied at the next restart.

Understanding Atomic Upgrades in Red Hat Enterprise Linux Atomic Host

The Red Hat Enterprise Linux Atomic Host system, when booted, is effectively inside a chroot, or "change root" environment; this happens at a very early stage of the boot inside a dracut plugin. The "physical root" is mounted on the /sysroot/ directory.

There is an /ostree/ toplevel directory (also available in the booted root, because the /ostree/ directory is a symlink to the /sysroot/ostree/ directory). This directory contains the following components:

  • repo

    The repo directory is analogous to a git source-code repository. It contains the files needed to create a deployment. This repository is version-controlled and contains information to allow multiple versions of files to be retained in parallel. The use of a repository keeps files that did not change during an upgrade from being duplicated on disk. This saves storage and allows for updates to be downloaded as deltas (only changed files), making updates significantly smaller in size.

  • deploy

    The deploy directory contains the parallel installs of different versions of the operating system. Within the /ostree/deploy/rhel-atomic-host/deploy/ directory are "deployments" that consist of hard links into the repository, as well as a writable copy of the /etc/ directory. Each file system tree represents a fully-bootable version of Red Hat Enterprise Linux Atomic Host.

  • deploy/rhel-atomic-host/var/

    This directory is shared between deployments, and appears as /var/ in the booted system via a bind mount.

  • boot/loader.0 and/or boot/loader.1

    Atomic upgrades work by swapping the bootloader configuration. The /boot/loader symbolic link points to either .0 or .1. When an upgrade is delivered, a new bootloader configuration is generated that points to the new deployment root.

  • boot.0.1 and/or boot.1.1

    These are the actual directories that contain the file system that will be booted. These directories consist of hard links into the repo directory to minimize disk space consumption.

The atomic upgrade works by booting either of the currently-installed versions of Red Hat Enterprise Linux Atomic Host and mounting the deploy directory as the root (/) file system.

In order to retain access to the root of the partition to facilitate upgrades, the true root directory of the partition file system is mounted on the /sysroot/ directory.

Warning: Do not directly modify the contents of the /ostree/ directory. Do not modify the /sysroot/ directory. Do not store files or create directories in the root directory, as they will not be preserved across upgrades.

Understanding Atomic Rollback in Red Hat Enterprise Linux Atomic Host

The only system change that is performed during an atomic rollback is to the bootloader order. Data remains untouched during rollback.

/var is shared between the two boot targets (between the two trees). This means that rollback will not affect /var/home, and will not affect the containers.

There is a copy of /etc in each deployment (in each tree). Configuration changes in /etc are rolled forward, but not backward. This means that all new trees downloaded after a change will reflect the change, however trees downloaded prior to the change do not reflect the change.

Running Containers on Red Hat Enterprise Linux Atomic Host

After you have installed Red Hat Enterprise Linux Atomic Host, it is ready to run containers.

For more information on using Docker formatted containers on Red Hat Enterprise Linux 7 Atomic Host, see the Get Started with Docker Formatted Container Images on Red Hat Systems guide.

Orchestrating Containers on Red Hat Enterprise Linux Atomic Host

Red Hat Enterprise Linux Atomic Host uses Kubernetes to orchestrate Linux containers. Documentation on Kubernetes can be found here: Get Started Orchestrating Containers with Kubernetes.

Installing Applications on Red Hat Enterprise Linux Atomic Host

Currently, package management is not supported on Red Hat Enterprise Linux Atomic Host. This means that you cannot use yum or rpm to install additional applications.

The preferred way of running applications on Red Hat Enterprise Linux Atomic Host is via Linux Containers.

Currently, if you want to add applications directly to Red Hat Enterprise Linux Atomic Host, you should place the applications in the /var/ directory. Many applications allow you to specify the installation directory during compilation. You might find it helpful to copy statically-linked binaries from other Red Hat Enterprise Linux servers.

Known Issues

These are the known issues.

  • rhn_register returns "command not found"

    Red Hat Network entitlement management is not supported in Red Hat Enterprise Linux Atomic Host. Use subscription-manager as described above.

  • error message "key file doesn't have value" while performing atomic host upgrade

    In some situations, atomic host upgrade fails with the error "key file doesn't have value" and an selinux error is logged in the /var/log/audit/audit.log file. In these situations it is necessary to re-register the instance by following these steps:

    1. Stop the rhsmcertd daemon by executing this command:

      $ sudo systemctl stop rhsmcertd
      
    2. Remove all existing registrations by executing this command:

      $ sudo subscription-manager clean
      
    3. Re-register the system as described in get started with red hat enterprise linux atomic host https://access.redhat.com/groups/964323/announcements/1119713

    4. Run the atomic host upgrade command.

    See the following bug for more information: BZ#1117420

  • atomic does not have an HTTP proxy configuration option

    If you are using a system that requires an HTTP proxy, the proxy is configured with an environment variable. In the future, a configuration option will be supported. To execute atomic with an HTTP proxy, use a command similar to the following one:

    $ sudo env http_proxy=http://proxy.example.com:port/ atomic host ...
    
  • I need to ensure that Red Hat Enterprise Linux Atomic Host is using a specific subscription pool

    It is possible to manually specify which subscription pool is used by the host by following this procedure:

    1. Register your machine.

      $ sudo subscription-manager register --username=<username>
      
    2. List the available subscriptions:

      $ sudo subscription-manager list --available
      

      The output of this command will look similar to that below. You will need to find the Pool ID for the Subscription which provides "Red Hat Enterprise Linux Atomic Host."

      +-------------------------------------------+
          Available Subscriptions
      +-------------------------------------------+
      Subscription Name: Red Hat Enterprise Linux Beta
      Provides:          ...
                         Red Hat Enterprise Linux Atomic Host
                         ...
      SKU:               RH...9
      Contract:          10...6
      Pool ID:           8a...b2
      Available:         Unlimited
      Suggested:         1
      Service Level:     Self-Support
      Service Type:      L1-L3
      Subscription Type: Instance Based
      Ends:              12/31/14
      System Type:       Physical
      

      If you do not find this subscription, it may be the case that you have used all of your entitlements. Run the command again, add the --all option, and search again. You may need to unregister another host.

    3. Attach the subscription to your host:

      $ sudo subscription-manager attach --pool <pool_id>
      

Release Notes

The update to Red Hat Enterprise Linux Atomic Host shipped on Friday October 24, 2014 features:

  • Installation support on "bare metal" via Anaconda, PXE, and Kickstart.
  • The GRUB2 bootloader
  • Code fixes and package updates
  • The replacement of geard with Kubernetes for container orchestration

To install using Anaconda, PXE, or Kickstart, download the ISO installation media as described in this document. To use the GRUB2 bootloader, you must perform a clean install. All other changes are available just by upgrading an existing Red Hat Enterprise Linux Atomic Host installation.

Documentation Release Notes

Additional information about subscription-manager can be found in section 3.2. Registering from the Command Line of Red Hat Subscription Management.

FAQ

    • Question: The commands rhn_register and rhn_regks return a message that reads "Command not found." What do I do in this situation?
    • Answer: Do not use RHN for updates. Instead, use Red Hat Subscription Manager (RHSM) as described above.
    • Question: After rebooting, I don't understand which image is the updated image. Can someone explain this?
    • Answer: host: 0 is the updated image.
    • Question: How do I reset the root password in Red Hat Enterprise Linux Atomic Host?
    • Answer: It is not possible to alter /.autorelabel in Red Hat Enterprise Linux Atomic Host, so you will not be able to reset the root password as described in the Red Hat Enterprise Linux documentation here: RHEL Password Reset Documentation Use the following procedure to enable selinux policy, so that you do not need to relabel:
    1. Modify the grub line starting with linux16. Append init=/bin/bash to the end of that line.

    2. Remount the root file system (/) with read and write permissions:

      # mount -o remount,rw /
      
    3. Mount the selinuxfs file system at /sys/fs/selinux:

      # mount -t selinuxfs selinuxfs /sys/fs/selinux
      
    4. Reload selinux policy:

      # /usr/sbin/load_policy -i
      
    5. Use the passwd command to change the root password:

      # passwd
      
    6. Remount the root file system read-only:

      # mount -o remount,ro /
      
    7. Sign out:

      # exit
      

      NOTE: This step produces a backtrace. This is expected behavior: pid 1, which in this case was set to bash, was exited. Proceed to the next step.

    8. Power cycle the machine.

Was this helpful?

We appreciate your feedback. Leave a comment if you would like to provide more detail.
It looks like we have some work to do. Leave a comment to let us know how we could improve.