Chapter 6. Running special container images

Use this chapter to learn about some special types of container images. 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. The podman container runlabel <label> command, allows you to execute the command defined in that <label> for the container image. Supported labels are install, run and uninstall.

6.1. Troubleshooting container hosts with toolbox

Instead of installing troubleshooting tools directly on your RHEL 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. Ensure that the toolbox and podman packages are installed: 

    # yum module list container-tools

    To install the full set of container tools, type: 

    # 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

  3. Open a bash shell to run commands inside the container: 

    # bash-4.4#

  4. 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

  5. Try to run a command inside your container. The sosreport command allows you 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.

    Note that sosreport command saves the report to the host (/host/var/tmp/sosreport-<ID>).

  6. 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]
  7. To leave the container and return to the host, type exit. The file is saved to /host/tmp/chronyd.core.809 and is available from /tmp/chronyd.core.809 on the host.

  8. To remove the toolbox-root container, type: 

    # podman rm toolbox-root

You can change the registry, image, or container name used by toolbox by adding the following:

  • 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.

6.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 than when run in a non-privileged container. Although sosreport can tell when it is running in a container, other commands need to 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 can, for example, delete files and directories mounted from the host that are 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. 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. You can run commands such as ipcs to see information about active message queues, shared memory segments, and semaphore sets on the host.

6.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.

6.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 specific 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 does not clean up the configuration files.

6.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).

  4. To leave the container and return to the host, type exit. 

    # exit