Chapter 5. Running special container images

Once you become familiar with common ways of working with containers and container images, use this section to learn about some special types of container images you might find useful. These include:

  • Toolbox: Instead of burdening a host system by installing tools needed to debug problems or monitor features, you can run the toolbox command. Toolbox starts a support-tools container image that holds tools you can use to run reports or diagnose problems on the host.
  • Runlabels: Some container images have labels built in that allow you to run those containers with preset options and arguments. When you do a podman run with a runlabel, the result can be a prescriptive set of features when you install, run, remove, or upgrade a container image.

5.1. Troubleshooting container hosts with toolbox

Instead of installing troubleshooting tools directly to your Red Hat Enterprise Linux 8 system, the toolbox utility offers a way to temporarily add those tools, then easily discard them when you are done. The toolbox utility works by:

  • Pulling the registry.redhat.io/rhel8/support-tools image to your local system.
  • Starting up a container from the image, then running a shell inside the container from which you can access the host system.

The support-tools container allows you to:

  • Run commands that may not be installed on the host system, such as sosreport, strace, or tcpdump, in a way that lets them act on the host system.
  • Install more software inside the container to use on the host system.
  • Discard the container when you are done.

The following illustrates a typical toolbox session.

Procedure

  1. Install the toolbox and podman packages, if you haven’t already. A good way to do that is to install the full set of container tools: 

    # yum module install container-tools -y

  2. Run the toolbox command to pull and run the support-tools image (inserting your Red Hat Customer Portal credentials when prompted): 

    # toolbox
Trying to pull registry.redhat.io/rhel8/support-tools...
...
Would you like to authenticate to registry: 'registry.redhat.io' and try again? [y/N] y
Username: johndoe
Password: *************
Login Succeeded!
Trying to pull registry.redhat.io/rhel8/support-tools...Getting image source signatures
...
Storing signatures
30e261462851238d38f4ef2afdaf55f1f8187775c5ca373b43e0f55722faaf97
Spawning a container 'toolbox-root' with image 'registry.redhat.io/rhel8/support-tools'
Detected RUN label in the container image. Using that as the default...
command: podman run -it --name toolbox-root --privileged --ipc=host --net=host --pid=host -e HOST=/host -e NAME=toolbox-root -e IMAGE=registry.redhat.io/rhel8/support-tools:latest -v /run:/run -v /var/log:/var/log -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -v /:/host registry.redhat.io/rhel8/support-tools:latest

bash-4.4#

    A bash shell opens, ready for you to run commands inside the container.

  3. From inside the container, the root file system on the host is available from the /host directory. The other directories shown are all inside the container. 

    # ls /
bin   dev  home  lib	lost+found  mnt  proc  run   srv  tmp  var
boot  etc  host  lib64	media	    opt  root  sbin  sys  usr

  4. From inside the container, you can try a command. For example, you can run sosreport to generate information about your system to send to Red Hat support: 

    bash-4.4# sosreport

sosreport (version 3.6)
This command will collect diagnostic and configuration information from
this Red Hat Enterprise Linux system and installed applications.

An archive containing the collected information will be generated in
/host/var/tmp/sos.u82evisb and may be provided to a Red Hat support
representative.
...
Press ENTER to continue, or CTRL-C to quit.   <Press ENTER>
...
Your sosreport has been generated and saved in:
  /host/var/tmp/sosreport-rhel81beta-12345678-2019-10-29-pmgjncg.tar.xz
The checksum is: c4e1fd3ee45f78a17afb4e45a05842ed
Please send this file to your support representative.

    Notice that sosreport is aware that you are in a container. As a result it knows to run on the host and save the report to the host (/host/var/tmp/sosreport-…​).

  5. Install a software package inside the container, to add tools that are not already in the container. For example, to get a core dump of a running process on the host, install the procps and gcore packages, use ps to get the process ID of a running daemon, then use gcore to get a core dump: 

    bash-4.4# yum install procps gdb -y
bash-4.4# ps -ef | grep chronyd
994        809     1  0 Oct28 ?        00:00:00 /usr/sbin/chronyd
bash-4.4# gcore -o /host/tmp/chronyd.core 809
Missing separate debuginfo for target:/usr/sbin/chronyd
Try: dnf --enablerepo='*debug*' install /usr/lib/debug/.build-id/96/0789a8a3bf28932b093e94b816be379f16a56a.debug
...
Saved corefile /host/tmp/chronyd.core.809
[Inferior 1 (process 809) detached]
# exit

    Once you type exit, you leave the container and return to the host. You can see that the file saved to /host/tmp/chronyd.core.809 is available from /tmp/chronyd.core.809 on the host.

At this point, the container is no longer running, but still exists on the system. You can choose to:

  • Start up the container again: Type toolbox again to restart the container (named toolbox-root). Any software additions or changes made previously to the container are maintained.
  • Start with a fresh container: To get rid of the old container, type podman rm toolbox-root. Then run toolbox again to start with a fresh support-tools container.

  • Start with different values: You can change the registry, image, or container name used by toolbox by adding the following values to your host /root/.toolboxrc file:

    • REGISTRY: Change the registry from which the toolbox image is pulled. For example: REGISTRY=registry.example.com
    • IMAGE: Change the image that is used. For example, IMAGE=mysupport-tools
    • TOOLBOX_NAME: Change the name assigned to the running container. For example, TOOLBOX_NAME=mytoolbox

The next time you run toolbox, the new values from the .toolboxrc file are used.

5.1.1. Opening privileges to the host

When you run other commands from within the support-tools container (or any privileged container), they can behave differently then when run in a non-privileged container. Although sosreport can tell when it is running in a container, other commands would have to specifically be told to act on the host system (the /host directory). Here are examples of features that may or not be open to the host from a container:

  • Privileges: A privileged container (--privileged) runs applications as root user on the host by default. The container has this ability because it runs with an unconfined_t SELinux security context. So you would be able to, for example, delete files and directories mounted from the host that were owned by the root user.
  • Process tables: Unlike a regular container, that only sees the processes running inside the container, running a ps -e command within a privileged container (with --pid=host set) lets you see every process running on the host. So, you can pass a process ID from the host to commands that run in the privileged container (for example, kill <PID>). With some commands, however, permissions issues could occur when they try to access processes from the container.
  • Network interfaces: By default, a container has only one external network interface and one loopback network interface. With network interfaces open to the host (--net=host), you can access those network interfaces directly from within the container.
  • Inter-process communications: The IPC facility on the host is accessible from within the privileged container. So, you can run commands such as ipcs to see information about active message queues, shared memory segments, and semaphone sets on the host.

5.2. Running containers with runlabels

Some Red Hat images include labels that provide pre-set command lines for working with those images. Using the podman container runlabel <label> command, you can tell podman to execute the command defined in that <label> for the image. Existing runlabels include:

  • install: Sets up the host system before executing the image. Typically, this results in creating files and directories on the host that the container can access when it is run later.
  • run: Identifies podman command line options to use when running the container. Typically, the options will open privileges on the host and mount the host content the container needs to remain permanently on the host.
  • uninstall: Cleans up the host system after you are done running the container.

Red Hat images that have one or more runlabels include the rsyslog and support-tools images. The following procedure illustrates how to use those images.

5.2.1. Running rsyslog with runlabels

The rhel8/rsyslog container image is made to run a containerized version of the rsyslogd daemon. Inside the rsyslog image are install, run and uninstall runlabels. The following procedure steps you through installing, running, and uninstalling the rsyslog image:

Procedure

  1. Pull the rsyslog image: 

    # podman pull registry.redhat.io/rhel8/rsyslog

  2. Display (but do not yet run) the install runlabel for rsyslog: 

    # podman container runlabel install --display rhel8/rsyslog
command: podman run --rm --privileged -v /:/host -e HOST=/host -e IMAGE=registry.redhat.io/rhel8/rsyslog:latest -e NAME=rsyslog registry.redhat.io/rhel8/rsyslog:latest /bin/install.sh

    This shows that the command will open privileges to the host, mount the host root filesystem on /host in the container, and run an install.sh script.

  3. Run the install runlabel for rsyslog: 

    # podman container runlabel install rhel8/rsyslog
command: podman run --rm --privileged -v /:/host -e HOST=/host -e IMAGE=registry.redhat.io/rhel8/rsyslog:latest -e NAME=rsyslog registry.redhat.io/rhel8/rsyslog:latest /bin/install.sh
Creating directory at /host//etc/pki/rsyslog
Creating directory at /host//etc/rsyslog.d
Installing file at /host//etc/rsyslog.conf
Installing file at /host//etc/sysconfig/rsyslog
Installing file at /host//etc/logrotate.d/syslog

    This creates files on the host system that the rsyslog image will use later.

  4. Display the run runlabel for rsyslog: 

    # podman container runlabel run --display rhel8/rsyslog
command: podman run -d --privileged --name rsyslog --net=host --pid=host -v /etc/pki/rsyslog:/etc/pki/rsyslog -v /etc/rsyslog.conf:/etc/rsyslog.conf -v /etc/sysconfig/rsyslog:/etc/sysconfig/rsyslog -v /etc/rsyslog.d:/etc/rsyslog.d -v /var/log:/var/log -v /var/lib/rsyslog:/var/lib/rsyslog -v /run:/run -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -e IMAGE=registry.redhat.io/rhel8/rsyslog:latest -e NAME=rsyslog --restart=always registry.redhat.io/rhel8/rsyslog:latest /bin/rsyslog.sh

    This shows that the command opens privileges to the host and mount a bunch of files and directories from the host inside the container, when it launches the rsyslog container to run the rsyslogd daemon.

  5. Execute the run runlabel for rsyslog: 

    # podman container runlabel run rhel8/rsyslog
command: podman run -d --privileged --name rsyslog --net=host --pid=host -v /etc/pki/rsyslog:/etc/pki/rsyslog -v /etc/rsyslog.conf:/etc/rsyslog.conf -v /etc/sysconfig/rsyslog:/etc/sysconfig/rsyslog -v /etc/rsyslog.d:/etc/rsyslog.d -v /var/log:/var/log -v /var/lib/rsyslog:/var/lib/rsyslog -v /run:/run -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -e IMAGE=registry.redhat.io/rhel8/rsyslog:latest -e NAME=rsyslog --restart=always registry.redhat.io/rhel8/rsyslog:latest /bin/rsyslog.sh
28a0d719ff179adcea81eb63cc90fcd09f1755d5edb121399068a4ea59bd0f53

    The rsyslog container opens privileges, mounts what it needs from the host, and runs the rsyslogd daemon in the background (-d). The rsyslogd daemon begins gathering log messages and directing messages to files in the /var/log directory.

  6. Display the uninstall runlabel for rsyslog: 

    # podman container runlabel uninstall --display rhel8/rsyslog
command: podman run --rm --privileged -v /:/host -e HOST=/host -e IMAGE=registry.redhat.io/rhel8/rsyslog:latest -e NAME=rsyslog registry.redhat.io/rhel8/rsyslog:latest /bin/uninstall.sh

  7. Run the uninstall runlabel for rsyslog: 

    # podman container runlabel uninstall rhel8/rsyslog
command: podman run --rm --privileged -v /:/host -e HOST=/host -e IMAGE=registry.redhat.io/rhel8/rsyslog:latest -e NAME=rsyslog registry.redhat.io/rhel8/rsyslog:latest /bin/uninstall.sh

    In this case, the uninstall.sh script just removes the /etc/logrotate.d/syslog file. Note that it doesn’t clean up the configuration files.

5.2.2. Running support-tools with runlabels

The rhel8/support-tools container image is made to run tools such as sosreport and sos-collector to help you analyze your host system. To simplify running the support-tools image, it includes a run runlabel. The following procedure describes how to run the support-tools image:

Procedure

  1. Pull the support-tools image: 

    # podman pull registry.redhat.io/rhel8/support-tools

  2. Display (but do not yet run) the run runlabel for support-tools: 

    # podman container runlabel run --display rhel8/support-tools
command: podman run -it --name support-tools --privileged --ipc=host --net=host --pid=host -e HOST=/host -e NAME=support-tools -e IMAGE=registry.redhat.io/rhel8/support-tools:latest -v /run:/run -v /var/log:/var/log -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -v /:/host registry.redhat.io/rhel8/support-tools:latest

    This shows that the command mounts directories and opens privileges and namespaces (ipc, net, and pid) to the host system. It assigns the host’s root file system to the /host directory in the container.

  3. Execute the run runlabel for support-tools: 

    # podman container runlabel run rhel8/support-tools
command: podman run -it --name support-tools --privileged --ipc=host --net=host --pid=host -e HOST=/host -e NAME=support-tools -e IMAGE=registry.redhat.io/rhel8/support-tools:latest -v /run:/run -v /var/log:/var/log -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -v /:/host registry.redhat.io/rhel8/support-tools:latest
bash-4.4#

    This opens a bash shell inside the support-tools container.

You can now run reports or debug tools against the host system (/host). When you are done, type exit to exit the shell and stop the container.