Debugging

Contents

• 1   Intro
• 2   Runtime
  • 2.1   Specify an output directory
  • 2.2   Add debug options to configuration file
• 3   Docker
  • 3.1   Clear Linux
  • 3.2   Other distributions (including CentOS 7 and RHEL 7)
• 4   Apply changes
• 5   Generate debug output
• 6   Further information
  • 6.1   Centos 7
  • 6.2   Other distributions

1   Intro

To enable full debug for cc-oci-runtime when running under docker, follow the instructions below.

Enabling debug output is slightly awkward due to the fact that docker does not currently provide a way to pass extra command-line options to the runtime.

To get around this restriction, the runtime provides a helper script called cc-oci-runtime.sh which reads extra arguments to pass to the runtime from /etc/cc-oci-runtime/cc-oci-runtime.sh.cfg on a normal system.

2   Runtime

Create runtime helper script configuration.

2.1   Specify an output directory

# Adjust directory as required
$ logdir=/tmp/cc-oci-runtime
$ sudo mkdir -p "$logdir"

2.2   Add debug options to configuration file

# Create the configuration directory
$ sudo mkdir -p /etc/cc-oci-runtime/

# Create the config file containing the extra command-line arguments to be
# passed to the real runtime.
$ export logdir=/run/cc-oci-runtime
$ cat << EOT | sudo tee -a /etc/cc-oci-runtime/cc-oci-runtime.sh.cfg
--hypervisor-log-dir
$logdir
EOT

3   Docker

The docker configuration needs to be updated to make use of the helper script, rather than calling the runtime directly.

3.1   Clear Linux

Docker on Clear Linux now auto-detects which runtime to used based on the underlying hardware. If the system is capable of running Clear Containers, the runtime will automatically be set to cc-oci-runtime, if not it will be set to runc.

This complicates enabling debugging slightly since the cc-oci-runtime.sh helper script cannot be configured to be used. Instead, you must run the commands below:

# Ensure that when docker calls the runtime, it actually loads the helper script (which will run the runtime)
$ sudo mv /usr/bin/cc-oci-runtime /usr/bin/cc-oci-runtime.REAL
$ sudo ln -s /usr/bin/cc-oci-runtime.sh /usr/bin/cc-oci-runtime

# Tell the helper script to call the real runtime binary
$ sudo sed -i 's/^runtime=\"\(.*\)\"/runtime="\1.REAL"/g' /usr/bin/cc-oci-runtime.sh

Note further that these commands will need to be re-run every time a system update installs a new version of the runtime.

See: https://github.com/01org/cc-oci-runtime/blob/master/documentation/Installing-Clear-Containers-on-ClearLinux.md

Older versions of Clear Linux:

# Tell docker to run the helper script as the runtime.
# This script will launch the real runtime with the correct arguments.
$ sudo sed -i -e 's!cor=cc-oci-runtime !cor=cc-oci-runtime.sh !g' /lib/systemd/system/docker-cor.service

3.2   Other distributions (including CentOS 7 and RHEL 7)

# Tell docker to run the helper script as the runtime.
# This script will launch the real runtime with the correct arguments.
$ sudo sed -i -e 's!cor=cc-oci-runtime !cor=cc-oci-runtime.sh !g' /etc/systemd/system/docker.service.d/clr-containers.conf

4   Apply changes

$ sudo systemctl daemon-reload
$ sudo systemctl restart docker

5   Generate debug output

With debug enabled, if you run, say:

$ docker run -ti busybox

... you should find the following files in /tmp/cc-oci-runtime/:

• cc-oci-runtime.log
• ${container}-hypervisor.stdout
• ${container}-hypervisor.stderr

Note that the global log file is always appended to, so if you run docker run twice, you'll end up with output for both containers in the same file.

6   Further information

Full instructions on how to use the helper script are at the top of the script itself.

6.1   Centos 7

$ more /usr/local/bin/cc-oci-runtime.sh

6.2   Other distributions

$ more /usr/bin/cc-oci-runtime.sh