This document provides instructions for deploying and using Fedora Atomic Host, an operating system designed for containers. It includes steps to: 1) Configure Fedora Atomic images using cloud-init files to set usernames, passwords, and hostnames. 2) Upgrade and rollback the Atomic host using rpm-ostree commands. 3) Understand how OSTree manages operating system updates and deployments. 4) Deploy Docker containers on the Atomic host and use Cockpit to manage containers.

1. Fedora Atomic Workshop
Hands on Guide
This document is prepared for Desktop/Laptops based on Linux platforms and just
enough to get you started. Explore more !!!
DVD:
Dvd contains the following images
1. Fedora-Cloud-Atomic-22-20150521.x86_64.qcow2: Fedora Atomic Qcow image for Linux distribution
2. Fedora-Cloud_Atomic-x86_64-22.iso: Atomic ISO image for installation on Virtual Machines or on Physical System.
3. Fedora-Cloud-Atomic-Vagrant-22-20150521.x86_64.vagrant-virtualbox.box: Image for Virtual Box (Windows)
4. cockpit.tar.gz: Cockpit docker image
5. Fedora-Docker-Base-22-20150521.x86_64.tar.xz: Fedora Docker image
Environment:
Virtual Machine Manager: KVM
Fedora Atomic image: Fedora 22 Atomic image(Fedora-Cloud-Atomic-22-20150521.x86_64.qcow2)
Activities:
A. Use Cloud-init to configure user name, password and set hostname
B. Upgrade the Fedora Atomic host
C. Understand OSTree and the layout
D. Start a simple docker container on Atomic Host
E. Use cockpit management interface
Setup the Fedora Atomic host
Activity 1: Cloud-init to configure user name, password and set hostname
The image Fedora-Cloud-Atomic-22-20150521.x86_64.qcow2 is available as a fully-configured disk image ready to be used with a Linux
hypervisor. You can customize the image using cloud-init. Once deployed, you cannot re-configure the image again using cloud-init.
Preparation for installation
Configuration options are set with a pair of cloud-init configuration files : metadata and userdata. Metadata is used to configure host
information like instance ID numbers, hostname, IP address, etc. Userdata is used for adding and modifying users, adding packages, calling
configuration management systems, etc. This information is injected into the host the first time it boots.
meta-data
A plain text file which provides information that identifies the instance of Fedora Atomic Host that is being installed. Its contents
should be similar to the following example:
The instance-id can be any identifying name and the local-hostname should be a host name that you wish to be set.
user-data
A plain text file which provides information about users on the system. This information will be used to enable access to the Fedora E
Atomic Host instance. By default, the root user is password-locked; therefore, if you do not create the user-data file, you will not be to
login. You can also set the password for the root user. The default user is fedora
You can also set up password less ssh login using keys by injecting the ssh keys for the fedora user. Generate custom keys using
ssh-keygen -f fatomic_rsa
Generating public/private rsa key pair.
<truncating output>
instance-id: FedoraAtomic0
local-hostname: FedoraAtomic

2. Fedora Atomic Workshop
Hands on Guide
An example of a user-data file is below: We are also re-setting the root password to fatomic
Choose an appropriate password for the users. Also replace the ssh-rsa key with the newly generated one. Print the newly created key using
the command “cat fatomic_rsa.pub”. Note the first line #cloud-config is mandatory
Next step is to create an iso image using these two files. This iso image will be provided during the boot process of the image. Below
command will create atomic0-cidata.iso in the current directory
Starting the Fedora Atomic Host for the first time
Copy the image Fedora-Cloud-Atomic-22-20150521.x86_64.qcow2 from DVD to your desktop or laptop
1. Open a terminal and execute the command virt-manager as the root user.
2. Hit the icon for “Creating a new virtual machine”
3. In the new Window, enter the following details
Name: FedoraAtomicHost
Select “Import Existing disk image”
Hit next
4. In the new window, hit the browse button and point to the location of the image Fedora-Cloud-Base-22-20150521.x86_64.qcow2. Select
the OS type as Linux and version as Fedora . Click the forward button
5. Allocate a minimum of 1024 MB RAM and 1 cpus. Hit forward. Select the option “Customize Configuration Before Install” and hit finish
6. Add a hardware -> storage->cdrom and point the iso image to the newly created atomic0-cidata.iso
7.Click finish.
8. Hit apply and click on the Begin installation option, VM will be spawned and you will notice the login screen in the VM console
Login to the Fedora Atomic Host
username: root
password: fatomic #If you have provided a different password in the user-data file, then use that
Note: Hostname is set to the name that you entered in the meta-data file. You can also login to the host via ssh using the keys
Activity 2: Upgrade the Fedora Atomic host [Needs internet access]
Fedora Atomic features a new update system for operating systems called rpm-ostree. In the default model, the RPMs are composed on a
server into an OSTree repository, and client systems can replicate in an image-like fashion, including incremental updates.
Unlike traditional operating system update mechanisms, it will automatically keep the previous version of the OS, always available for
rollback. Upgrade the atomic host using the command atomic host upgrade. After upgrade,reboot the host using systemctl reboot
-bash-4.2# atomic host upgrade
Updating from: fedora-atomic:fedora-atomic/f22/x86_64/docker-host
ostadmin: Creating deployment /ostree/deploy/fedora-atomic-
controller/deploy/6b6b1362241f1c658b54797b51c2215e32b0978f2201eeb7cd2068276adb9015.2
ostadmin: Processing /etc: 1 modified, 0 removed, 6 added
Transaction complete; bootconfig swap: yes deployment count change: 0)
Updates prepared for next boot; run "systemctl reboot" to start a reboot
#cloud-config
ssh_pwauth: True
ssh_authorized_keys:
- ssh-rsa new publickey here user@host #REPLACE this line starting from ssh-rsa with the key that is found in atomic_rsa.pub
chpasswd:
list: |
root:fatomic
fedora:fatomic
expire: False
# genisoimage -output atomic0-cidata.iso -volid cidata -joliet -rock user-data meta-data

3. Fedora Atomic Workshop
Hands on Guide
“atomic host upgrade”, checks the repository URL specified in /ostree/repo/config to check for an updated version.
If a new version is found, it will first be downloaded, then deployed. At that point, a three-way merge of configuration is performed, using the
new /etc as a base, and applying your changes on top. You can also use rpm-ostree upgrade
RollBack:
To rollback to the previous version, execute the command atomic host rollback / rpm-ostree rollback
The atomic host should be rebooted after the rollback using systemctl reboot
Activity 3: Understand OSTree and the layout
OSTree is considered as the git for operating system binaries. After upgrading the atomic host, you will have two versions of docker on the
atomic host. Execute the below command to check the version of the kernel
Downgrade the atomic host using, rpm-ostree rollback(reboot the host) and then check for the version of kernel
Notice the difference in version. You can switch between the updates without overwriting the old version.
OSTree only preserves /var across upgrades. Since only /var is preserved, /root is bind mounted as /var/roothome. Similarly /home is bind
mounted as /var/home and /tmp to /sysroot/tmp (Just few examples top level writable directories)
When the rpm-ostree upgrade/atomic host upgrade command is executed, it checks the OSTree repository. If any updates are available,
then it will replicate the contents and creates a new root for the next reboot. Any changes made to /etc between upgrades are propagated
forwards and all local state in /var/ is shared.
Observe or check the output of the command ostree admin status/atomic host status on the atomic host system.
The * in the output tell us which deployment will be chosen as the default
Touch a file " touch /etc/sysconfig/touch". After creating the file execute the command "ostree admin config-diff" . It will list of configuration
files that were modified since the initial deployment.
A denotes a file was added to /etc while M denotes the file was modified
--bash-4.3# rpm-ostree rollback
Moving '06a63ecfcf053d1625e9ddf406429eef3c7fe3ecccbe636a54b90175a5899e7d.0' to be first deployment
Transaction complete; bootconfig swap: yes deployment count change: 0
Sucessfully reset deployment order; run "systemctl reboot" to start a reboot
-bash-4.2# rpm -q kernel
kernel-4.0.4-303.fc22.x86_64
-bash-4.2# rpm -q kernel
kernel-4.0.4-301.fc22.x86_64
-bash-4.3# atomic host status
TIMESTAMP (UTC) VERSION ID OSNAME REFSPEC
2015-05-21 19:01:46 22.17 06a63ecfcf fedora-atomic fedora-atomic:fedora-atomic/f22/x86_64/docker-host
* 2015-06-17 19:33:30 22.40 1fa7919b3d fedora-atomic fedora-atomic:fedora-atomic/f22/x86_64/docker-host
-bash-4.3# ostree admin config-diff
M adjtime
M nsswitch.conf
M shadow
M localtime
A sysconfig/network
A sysconfig/touch

4. Fedora Atomic Workshop
Hands on Guide
/boot
When a upgrade is installed, it places a file like /boot/loader/entries/ostree-osname-checksum.conf in /boot directory.
Lets check the contents of one of the file
In the above output, observe the parameter called ostree. This ostree helps the initrd to find the specified deployment and chroot into it.
Activity 4: Deploying/Starting a simple container on Fedora Atomic Host
If the desktop/laptop has internet, then the following command can be executed on the atomic host to pull the Fedora 22 docker image-like
If not then copy Fedora-Docker-Base-22-20150521.x86_64.tar.xz from DVD to Atomic Host and then manually load the container image-like
After loading the image, execute docker image to list all the available images on the host
Using base Fedora 22 container image, start a simple container on the atomic host for the bash application. Enter “exit” to exit from the
container
Activity 5: Deploying Container manager service: Cockpit
Cockpit is under rapid development and not production ready. Cockpit runs inside a privileged container and is able to monitor and
administer several servers at the same time. Each server only needs ```cockpit-bridge``` and ```cockpit-shell```, which are part of Fedora
Atomic 22, in order to get connected to Cockpit. You can manage all other containers running in the host.
If the desktop/laptop has internet, then the following command can be executed on the atomic host
If not, the copy the cockpit.tar.gz from DVD to laptop and then to atomic host VM. Import the docker cockpit image and then install it
Find the ip address of the Atomic using the command ifconfig ens3 [replace ens3 with the appropriate interface name]
# atomic run cockpit/ws
--bash-4.3# ls /boot/loader/entries/
ostree-fedora-atomic-0.conf ostree-fedora-atomic-1.conf
initrd /ostree/fedora-atomic-95140f890a8d43bc1fa43e52d2a0348009d913d28e88bb1619cc0646bd6a7ede/initramfs-4.0.4-
303.fc22.x86_64.img
options rd.lvm.lv=fedora_dhcp200-186/swap rd.lvm.lv=fedora_dhcp200-186/root quiet rhgb root=/dev/mapper/fedora_dhcp200--186-root
ostree=/ostree/boot.0/fedora-atomic/95140f890a8d43bc1fa43e52d2a0348009d913d28e88bb1619cc0646bd6a7ede/0
title Fedora 22 (Twenty Two) 22.40 (ostree)
linux /ostree/fedora-atomic-95140f890a8d43bc1fa43e52d2a0348009d913d28e88bb1619cc0646bd6a7ede/vmlinuz-4.0.4-303.fc22.x86_64
version 1
# docker load -i cockpit.tar.gz
# atomic run <image-id> #Find the image id of cockpit using the command docker images. It should be 0c45b9010fba
/usr/bin/docker run -d --privileged --pid=host -v /:/host 0c45b9010fba /container/atomic-run --local-ssh
74d7b5d7bc77afa0ad216bb55bf79ec527334ad9aa0858e30d00b85071ab95ab
# docker pull fedora
# docker load -i Fedora-Docker-Base-22-20150521.x86_64.tar.xz
# docker run -it --rm Fedora-Docker-Base-22-20150521.x86_64 bash
# docker images

5. Fedora Atomic Workshop
Hands on Guide
Start a firefox browser on the desktop/laptop system and type the following htp://<ipaddress>:9090 and then press enter. Cockpit by default
uses a self signed certificate. In the browser, select the option “I understand the risks” , followed by “Add Exception button”. When you hit
add exception button, it will create a new popup window. Select the button “confirm security exception”.
At the cockpit login screen, enter the following credentials
username:root
password: fatomic #if you had provided a different root password,then use the correct one
After logging in, Perform the following steps
Hit “Containers” option after logging in(Left corner). It will list all the available docker images on the host. Docker images are listed on the left
side. Also you can see the list of containers that are running on the system
Let's start a container from the VM console. From the atomic host console, start a simple container
T
Allow the container to run. Don't enter exit.
Go back to the cockpit console. You will notice a container with the name firstcontainer is running. Click on the firstcontainer. You will notice
the console of the container in the browser.
Console of the container
# docker run -it --name=firstcontainer Fedora-Docker-Base-22-20150521.x86_64 bash
Bash-4.2#

6. Fedora Atomic Workshop
Hands on Guide
Using cockpit, you can start, stop, restart and delete container as well
To stop the container, click the “stop” button . You will see the “firstcontainer” as stopped. If you go back to the vmconsole, you notice that the
firstcontainer has been stopped. You can start firstcontainer again by hitting the “play” button on the cockpit console.
Using the existing images, you can start a container from the console cockpit itself. Also you can download new container images from the
cockpit console itself.
To start a container from console cockpit, you need to select the container image and then hit the play button. While starting a container from
the console cockpit, you can choose whether to attach a terminal, whether to assign any ports or provide any specific ports, set any memory
limits etc.

7. Fedora Atomic Workshop
Hands on Guide
Miscellaneous
Possible issues:
1. While starting the atomic host and if you notice “no bootable device found” message, then make sure the storage format
of the imported image for the vm in the virt-manager is set as qcow2
2. If the atomic host does not receive any IP address, then make sure the default NAT interface is enabled(virbr0) or verify
whether the NIC of the Atomic host system is configured to use the default NAT interface
3. If you notice Atomic host getting hung, then check whether the underlying disk where the VM image of the atomic host is
hosted has enough free space
4. If you are not able to login in to the atomic host, use the below file user-data as such
Meetup group:
If you are interested to know more about Docker/Containers and want to stay in touch, then join Docker Pune meetup group
http://www.meetup.com/Docker-Pune
References
Project Atomic: http://www.projectatomic.io
OSTree: https://wiki.gnome.org/Projects/OSTree
Images: https://getfedora.org/cloud/download/atomic.html
Hands on Guide Prepared by Document reviewers:
Ranjith Rajaram Leo Thomas
twitter: @ranjithrajaram tleothomas@gmail.com
Email: ranjith@redhat.com
#cloud-config
chpasswd:
list: |
root:fatomic
fedora:fatomic
expire: False