Table Of Contents

Previous topic

Seamless execution mode

Next topic

Deep file copying (okapi)

This Page

CDE options

Every non-trivial application has tunable options, and CDE is no exception. My design philosophy is to provide a good set of default options that works “out-of-the-box” for most Linux users but also provide the means for power users to customize their CDE experience.

cde.options file

For simplicity, you specify all CDE options in a cde.options file. The first time you run cde in a particular directory, CDE will create a new cde.options file in that directory, pre-seeded with sensible default values. When you run cde, it will copy cde.options into cde-package/. When you later run cde-exec, it will refer to the copy of cde.options within cde-package/.

The default cde.options file contains roughly the following contents:

# cde.options v1 (do not alter this first line!)

# These directories often contain pseudo-files that shouldn't be tracked
ignore_prefix=/dev/
ignore_exact=/dev
ignore_prefix=/proc/
ignore_exact=/proc
ignore_prefix=/sys/
ignore_exact=/sys
ignore_prefix=/var/cache/
ignore_prefix=/var/lock/
ignore_prefix=/var/log/
ignore_prefix=/var/run/
ignore_prefix=/var/tmp/
ignore_prefix=/tmp/
ignore_exact=/tmp

# un-comment the entries below if you think they might help your app:
#ignore_exact=/etc/ld.so.cache
#ignore_exact=/etc/ld.so.preload
#ignore_exact=/etc/ld.so.nohwcap

# Ignore .Xauthority to allow X Windows programs to work
ignore_substr=.Xauthority

# Ignore so that networking can work properly
ignore_exact=/etc/resolv.conf
# These files might be useful to ignore along with /etc/resolv.conf
# (un-comment if you want to try them)
#ignore_exact=/etc/host.conf
#ignore_exact=/etc/hosts
#ignore_exact=/etc/nsswitch.conf
#ignore_exact=/etc/gai.conf

# Access the target machine's password files:
# (some programs like texmacs need these lines to be commented-out,
#  since they try to use home directory paths within the passwd file,
#  and those paths might not exist within the package.)
ignore_prefix=/etc/passwd
ignore_prefix=/etc/shadow

# These environment vars might lead to 'overfitting' and hinder portability
ignore_environment_var=DBUS_SESSION_BUS_ADDRESS
ignore_environment_var=ORBIT_SOCKETDIR
ignore_environment_var=SESSION_MANAGER
ignore_environment_var=XAUTHORITY
ignore_environment_var=DISPLAY

As you can probably guess, this file allows you to specify what paths and environment variables CDE should ignore when executing commands within your package. The syntax is simple: a token like ignore_prefix followed by an equals sign and then the value, which stretches until the end of the line. Leading and trailing whitespace are stripped during parsing, so I suppose this format doesn’t support paths with trailing spaces (but who uses those anyways???).

Ignoring paths

When you execute a command prepended by cde-exec, recall that your current working directory must be within cde-root/ inside of a package (unless you’re running in seamless execution mode). CDE ensures that your command cannot access any files outside of the cde-root/ sandbox, because it redirects all paths inside of cde-root/. However, there are situations in which you would like commands to access files outside of the sandbox. To achieve this goal, you can tell CDE to ignore certain paths by specifying them using ignore_* options:

CDE will ignore any path that exactly matches the string following ignore_exact= (so don’t add any extra spaces!). Similarly, CDE will ignore any path that starts with the prefix matching the string following ignore_prefix=. A prefix ignore is useful for, say, ignoring all paths within a directory and all of its sub-directories. Lastly, CDE will ignore any path that contains a substring matching the string following ignore_substr=.

By ‘ignore’, I mean that cde will not copy those files into cde-package/, and correspondingly, cde-exec will access those files by their true paths rather than redirecting their paths into the cde-root/ jail. Thus, you can use these ignore options to selectively ‘poke holes’ in the sandbox.

Note that CDE simply does string comparisons on the exact paths that the target program issues in file-related system calls, so craft your ignore paths carefully!

Explicitly redirecting paths

The opposite of specifying paths to ignore is specifying paths to redirect into cde-root/. The redirect_exact, redirect_prefix, and redirect_substr options are the complements of the corresponding ignore_* options. For example, if you specify:

ignore_prefix=/home/pg/
redirect_prefix=/home/pg/relevant-dir/

then CDE will ignore everything inside of /home/pg/ except for the contents of /home/pg/relevant-dir/. Redirect options always take precedence over ignore options (regardless of the order they appear in the cde.options file).

By ‘redirect’, I mean that cde will actually copy those files into cde-package/, and correspondingly, cde-exec will redirect their paths into the cde-root/ jail.

Note that by default, all paths are redirected into the cde-root jail (unless explicitly ignored). The reason why the redirect options exist is that they allow you to override and fine-tune particular ignore paths.

Process-specific ignore paths

There are situations where you want to ignore paths only for a specific process. For example, on some distros, executing the BASH shell within a CDE package causes mysterious crashes (for reasons unrelated to CDE). A workaround is to tell cde-exec to “ignore” BASH; that is, to use the native BASH on the target machine rather than the version of BASH from the package. However, simply ignoring all paths to files that the BASH process attempts to access leads to incorrect behavior, since BASH shell scripts are often used to invoke other programs. The paths to these other programs (e.g., Python, gcc) should not be ignored, since we want cde-exec to access those files from within the package, not on the target machine. Thus, we need a way of telling cde-exec to only ignore certain files when trying to run BASH. You can do so by including the following lines in cde.options:

ignore_process=/bin/sh
{
  process_ignore_prefix=/lib/
  process_ignore_prefix=/etc/
}

The syntax for this process-specific ignore option starts with ignore_process= on a line by itself, which specifies the name of the process to ignore. Note that in the above example, we wrote /bin/sh, since BASH is often executed as /bin/sh. Then this line is followed by a series of process_ignore_prefix= lines surrounded by braces. The opening and closing braces must be the only tokens on their respective lines. Indentation of the process_ignore_prefix= lines doesn’t matter, though.

Each process_ignore_prefix entry represents a prefix of a path to ignore only when executing the ignored process. In the above example, when executing /bin/sh, we are telling cde-exec to ignore all paths starting with /lib/ and /etc/, thus loading those files natively from the target machine. These are precisely the directories from which the BASH process needs to load auxiliary and shared libraries files.

(In order to get this example to work on your 64-bit target machine, you might need to replace /lib/ with /lib64/, depending on where BASH loads its libraries from. Use ldd /bin/sh to find out.)

Ignoring environment variables

Recall that cde-exec sets up an environment with values loaded from the cde-package/cde.full-environment file. Sometimes certain variables might cause problems when you transfer the package to another machine, since they contain machine- or distro-specific values. You can make your packages more portable by explicitly ignoring those variables using the ignore_environment_var option and instead using the default versions on the target machine.

Command-line options

CDE is designed to work well “out-of-the-box” without the user needing to mess around with command-line flags or the cde.options file. However, for the intrepid, these command-line options are available:

  • cde -o <output dir> : Create and use <output dir> as an output directory instead of the default cde-package/ directory.
  • cde -p : Output a provenance.log file that contains a log of all the files opened by and sub-processes spawned by the target process.
  • cde-exec -l : Use the native dynamic linker on the machine rather than the dynamic linker within the CDE package, which makes execution more robust but less portable.