Chapter 1. Get Started with Linux Containers

To get images from a remote registry (such as Red Hat’s own Docker registry) and add them to your local system, use the podman pull command:

# podman pull <registry>[:<port>]/[<namespace>/]<name>:<tag>

The <registry> is a host that provides the registry service on TCP <port> (default: 5000). Together, <namespace> and <name> identify a particular image controlled by <namespace> at that registry. Some registries also support raw <name>; for those, <namespace> is optional. When it is included, however, the additional level of hierarchy that <namespace> provides is useful to distinguish between images with the same <name>. For example:

The registries that Red Hat supports are registry.redhat.io (requiring authentication) and registry.access.redhat.com (requires no authentication, but is deprecated). For details on the transition to registry.redhat.io, see Red Hat Container Registry Authentication . Before you can pull containers from registry.redhat.io, you need to authenticate. For example:

# podman login registry.redhat.io
Username: myusername
Password: ************
Login Succeeded!

To get started with container images, you can use the pull option to pull an image from a remote registry. To pull the RHEL 7 UBI base image and rsyslog image from the Red Hat registry, type:

# podman pull registry.access.redhat.com/ubi7/ubi
# podman pull registry.access.redhat.com/rhel7/rsyslog

An image is identified by a repository name (registry.access.redhat.com), a namespace name (rhel7) and the image name (rsyslog). You could also add a tag (which defaults to :latest if not entered). The repository name rhel7, when passed to the podman pull command without the name of a registry preceding it, is ambiguous and could result in the retrieval of an image that originates from an untrusted registry. If there are multiple versions of the same image, adding a tag, such as latest to form a name such as rsyslog:latest, lets you choose the image more explicitly.

To see the images that resulted from the above podman pull command, along with any other images on your system, type podman images:

# podman images
REPOSITORY
             TAG        IMAGE ID      CREATED       VIRTUAL SIZE
registry.access.redhat.com/rhel7/rsyslog
             latest     39ec6b2004a3  9 days ago    236 MB
registry.access.redhat.com/ubi7/ubi
             latest     967cb403b7ee  3 days ago     215 MB

Using podman images you can see which images have been pulled to your local system. To look at the metadata associated with an image, use podman inspect.

# podman images
REPOSITORY                                            TAG    IMAGE ID     CREATED      VIRTUAL SIZE
registry.access.redhat.com/rhel7/rsyslog              latest 39ec6b2004a3 10 days ago  236 MB
registry.access.redhat.com/ubi7/ubi                   latest 967cb403b7ee 10 days ago  215 MB
registry.access.redhat.com/rhscl/postgresql-10-rhel7  1-35   27b15d85ca6b 3 months ago 336 MB

# skopeo inspect docker://registry.access.redhat.com/ubi7/ubi
   {
    "Name": "registry.access.redhat.com/ubi7/ubi",
    "Digest": "sha256:caf8d01ac73911f872d184a73a5e72a1eeb7bba733cbad13e8253b567d16899f",
    "RepoTags": [
        "latest",
        "7.6",
        "7.7"
    ],
    "Created": "2019-08-01T09:29:20.753891Z",
    "DockerVersion": "1.13.1",
    "Labels": {
        "architecture": "x86_64",
        "authoritative-source-url": "registry.access.redhat.com",
        "build-date": "2019-08-01T09:28:54.576292",
        "com.redhat.build-host": "cpt-1007.osbs.prod.upshift.rdu2.redhat.com",
        "com.redhat.component": "ubi7-container",

You can add names to images to make it more intuitive to understand what they contain. Tagging images can also be used to identify the target registry for which the image is intended. Using the podman tag command, you essentially add an alias to the image that can consist of several parts. Those parts can include:

registryhost/username/NAME:tag

You can add just NAME if you like. For example:

# podman tag 967cb403b7ee myrhel7

Using podman tag, the name myrhel7 now also is attached to the ubi7/ubi image (image ID 967cb403b7ee) on your system. So you could run this container by name (myrhel7) or by image ID. Notice that without adding a :tag to the name, it was assigned :latest as the tag. You could have set the tag to 7.7 as follows:

# podman tag 967cb403b7ee myrhel7:7.7

To the beginning of the name, you can optionally add a user name and/or a registry name. The user name is actually the repository on Docker.io or other registry that relates to the user account that owns the repository. Here’s an example of adding a user name:

# podman tag 967cb403b7ee jsmith/myrhel7
# podman images | grep 967cb403b7ee
localhost/jsmith/myrhel7             latest  967cb403b7ee   10 days ago  215 MB
localhost/myrhel7                    7.7     967cb403b7ee   10 days ago  215 MB
registry.access.redhat.com/ubi7/ubi  latest  967cb403b7ee   10 days ago  215 MB

Above, you can see all the image names assigned to the single image ID.

If you want to save a container image you created, you can use podman save to save the image to a tarball. After that, you can store it or send it to someone else, then reload the image later to reuse it. Here is an example of saving an image as a tarball:

# podman save -o myrsyslog.tar registry.access.redhat.com/rhel7/rsyslog
# ls
myrsyslog.tar

The myrsyslog.tar file should now be stored in your current directory. Later, when you are ready to reuse the tarball as a container image, you can import it to another podman environment as follows:

# cat myrsyslog.tar | podman import - rhel7/myrsyslog
Getting image source signatures
Copying blob baa75547a1df done
Copying config 6722efbc0c done
Writing manifest to image destination
Storing signatures
6722efbc0ce5591161f773ef6371390965dc54212ac710c7517ee6d55eee6485
# podman images | grep myrsyslog
docker.io/rhel7/myrsyslog   latest  6722efbc0ce5  50 seconds ago   236 MB

To see a list of images that are on your system, run the podman images command. To remove images you no longer need, use the podman rmi command, with the image ID or name as an option. (You must stop any containers run from an image before you can remove the image.) Here is an example:

# podman rmi rhel-init
7e85c34f126351ccb9d24e492488ba7e49820be08fe53bee02301226f2773293

You can remove multiple images on the same command line:

# podman rmi registry.access.redhat.com/rhel7/rsyslog support-tools
46da8e23fa1461b658f9276191b4f473f366759a6c840805ed0c9ff694aa7c2f
85cfba5cd49c84786c773a9f66b8d6fca04582d5d7b921a308f04bb8ec071205

If you want to clear out all your images, you could use a command like the following to remove all images from your local registry (make sure you mean it before you do this!):

# podman rmi $(podman images -a -q)
1ca061b47bd70141d11dcb2272dee0f9ea3f76e9afd71cd121a000f3f5423731
ed904b8f2d5c1b5502dea190977e066b4f76776b98f6d5aa1e389256d5212993
83508706ef1b603e511b1b19afcb5faab565053559942db5d00415fb1ee21e96

To remove images that have multiple names (tags) associated with them, you need to add the force option to remove them. For example:

# podman rmi $(podman images -a -q)
unable to delete eb205f07ce7d0bb63bfe5603ef8964648536963e2eee51a3ebddf6cfe62985f7 (must force) - image is referred to in multiple tags
unable to delete eb205f07ce7d0bb63bfe5603ef8964648536963e2eee51a3ebddf6cfe62985f7 (must force) - image is referred to in multiple tags

# podman rmi -f eb205f07ce7d
eb205f07ce7d0bb63bfe5603ef8964648536963e2eee51a3ebddf6cfe62985f7

When you execute a podman run command, you essentially spin up and create a new container from a container image. The command you pass on the podman run command line sees the inside the container as its running environment so, by default, very little can be seen of the host system. For example, by default, the running applications sees:

If you want to make a directory from the host available to the container, map network ports from the container to the host, limit the amount of memory the container can use, or expand the CPU shares available to the container, you can do those things from the podman run command line. Here are some examples of podman run command lines that enable different features.

EXAMPLE #1 (Run a quick command): This podman command runs the cat /etc/os-release command to see the type of operating system used as the basis for the container. After the container runs the command, the container exits and is deleted (--rm).

# podman run --rm registry.access.redhat.com/ubi7/ubi cat /etc/os-release
NAME="Red Hat Enterprise Linux Server"
VERSION="7.7 (Maipo)"
ID="rhel"
ID_LIKE="fedora"
VARIANT="Server"
VARIANT_ID="server"
VERSION_ID="7.7"
PRETTY_NAME="Red Hat Enterprise Linux Server 7.7 (Maipo)"
...

EXAMPLE #2 (View the Dockerfile in the container): This is another example of running a quick command to inspect the content of a container from the host. All layered images that Red Hat provides include the Dockerfile from which they are built in /root/buildinfo. In this case you do not need to mount any volumes from the host.

# podman run --rm registry.access.redhat.com/ubi7/ubi ls /root/buildinfo
Dockerfile-ubi7-7.7-99

Now you know what the Dockerfile is called, you can list its contents:

# podman run --rm registry.access.redhat.com/ubi7/ubi \
    cat /root/buildinfo/Dockerfile-ubi7-7.7-99
FROM sha256:94577870ec362083c6513cfadb00672557fc5dd360e67befde6c81b9b753d06e
RUN mv -f /etc/yum.repos.d/ubi.repo /tmp || :

MAINTAINER Red Hat, Inc.

LABEL com.redhat.component="ubi7-container"
LABEL name="ubi7"
LABEL version="7.7"
...

EXAMPLE #3 (Run a shell inside the container): Using a container to launch a bash shell lets you look inside the container and change the contents. This sets the name of the container to mybash. The -i creates an interactive session and -t opens a terminal session. Without -i, the shell would open and then exit. Without -t, the shell would stay open, but you wouldn’t be able to type anything to the shell.

Once you run the command, you are presented with a shell prompt and you can start running commands from inside the container:

# podman run --name=mybash -it registry.access.redhat.com/ubi7/ubi /bin/bash
[root@ed904b8f2d5c/]#  yum install nmap
[root@ed904b8f2d5c/]#  ps -ef
UID        PID  PPID  C STIME TTY          TIME CMD
root         1     0  0 00:46 pts/0    00:00:00 /bin/bash
root        35     1  0 00:51 pts/0    00:00:00 ps -ef
[root@49830c4f9cc4/]# exit

Although the container is no longer running once you exit, the container still exists with the new software package still installed. Use podman ps -a to list the container:

# podman ps -a
CONTAINER ID IMAGE                 COMMAND   CREATED        STATUS                PORTS NAMES        IS INFRA
1ca061b47bd7 .../ubi8/ubi:latest   /bin/bash 8 minutes ago  Exited 12 seconds ago       musing_brown false
...

You could start that container again using podman start with the -ai options. For example:

# podman start -ai mybash
[root@ed904b8f2d5c/]#

EXAMPLE #4 (Bind mounting log files): One way to make log messages from inside a container available to the host system is to bind mount the host’s /dev/log device inside the container. This example illustrates how to run an application in a RHEL container that is named log_test that generates log messages (just the logger command in this case) and directs those messages to the /dev/log device that is mounted in the container from the host. The --rm option removes the container after it runs.

# podman run --name="log_test" -v /dev/log:/dev/log --rm \
     registry.access.redhat.com/ubi7/ubi logger "Testing logging to the host"
# journalctl -b | grep Testing
Aug 11 18:22:48 rhel76_01 root[6237]: Testing logging to the host

After you have some running container, you can list both those containers that are still running and those that have exited or stopped with the podman ps command. You can also use the podman inspect to look at specific pieces of information within those containers.

# podman run -d registry.access.redhat.com/rhel7/rsyslog
# podman ps
CONTAINER ID IMAGE          COMMAND         CREATED       STATUS            PORTS NAMES
50e5021715e4 rsyslog:latest /bin/rsyslog.sh 5 seconds ago Up 3 seconds ago  epic_torvalds

# podman ps -a
CONTAINER ID IMAGE           COMMAND    CREATED        STATUS                   PORTS NAMES
86a6f6962042 ubi7/ubi:latest /bin/bash  11 minutes ago Exited (0) 6 minutes ago       mybash

# podman inspect 50e5021715e4
    ...
[
    {
        "Id": "50e5021715e4829a3a37255145056ba0dc634892611a2f1d71c647cf9c9aa1d5",
        "Created": "2019-08-11T18:27:55.493059669-04:00",
        "Path": "/bin/rsyslog.sh",
        "Args": [
            "/bin/rsyslog.sh"
        ],
        "State": {
            "OciVersion": "1.0.1-dev",
            "Status": "running",
            "Running": true,
    ...

# podman inspect --format='{{.NetworkSettings.IPAddress}}' 50e5021715e4
10.88.0.36

# podman inspect --format='{{.State.Pid}}' 50e5021715e4
7544
# ps -ef | grep 7544
root     7544 7531  0 10:30 ?        00:00:00 /usr/sbin/rsyslogd -n
# podman inspect --format='{{.State.StartedAt}}' 50e5021715e4
2019-08-11 18:27:57.946930227 -0400 EDT

If you ran a container, but didn’t remove it (--rm), that container is stored on your local system and ready to run again. To start a previously run container that wasn’t removed, use the start option. To stop a running container, use the stop option.

# podman start myrhel_httpd
myrhel_httpd

# podman start -a -i agitated_hopper
[root@d65aecc325a4 /]#  exit

# podman stop 74b1da000a11
74b1da000a114015886c557deec8bed9dfb80c888097aa83f30ca4074ff55fb2

# podman kill --signal="SIGHUP" 74b1da000a11
74b1da000a114015886c557deec8bed9dfb80c888097aa83f30ca4074ff55fb2

To see a list of containers that are still hanging around your system, run the podman ps -a command. To remove containers you no longer need, use the podman rm command, with the container ID or name as an option. Here is an example:

# podman rm goofy_wozniak

You can remove multiple containers on the same command line:

# podman rm clever_yonath furious_shockley drunk_newton

If you want to clear out all your containers, you could use a command like the following to remove all containers (not images) from your local system (make sure you mean it before you do this!):

# podman rm $(podman ps -a -q)