Table Of Contents

Previous topic

CDE user manual

Next topic

Seamless execution mode

This Page

Basic CDE usage

This document illustrates basic usage of cde and cde-exec to create and execute a CDE package, respectively.

Running cde to create a package

When you execute any Linux command prepended with the cde binary, CDE will execute that command, track all files that it and its sub-processes access (using ptrace), and copy those files into a package in the cde-package/ sub-directory of your current working directory.

If the cde-package/ sub-directory does not yet exist, then CDE will create it; otherwise, CDE will add files to the already-existent package.

You should be able to move that package to any other Linux machine with a compatible kernel version (e.g., 2.6.X) and architecture (e.g., i386, x86-64) as yours and re-run the original command without first installing anything.

I’ll demonstrate with a simple example involving the cat command. I created a cat-test/ sub-directory within my home directory (/home/pgbovine/) and put a hello.txt text file in there. Running cat on hello.txt prints its contents, “hello world”:

$ pwd
/home/pgbovine/cat-test

$ ls
hello.txt

$ cat hello.txt
hello world

Now when I run cde cat hello.txt, the command prints “hello world” as usual, and CDE also creates a cde-package/ sub-directory:

$ cde cat hello.txt
hello world

$ pwd
/home/pgbovine/cat-test

$ ls
cde.options  cde-package/  hello.txt

Let’s see what’s in this package:

$ find cde-package/
cde-package/
cde-package/cde-root
cde-package/cde-root/home
cde-package/cde-root/home/pgbovine
cde-package/cde-root/home/pgbovine/cat-test
cde-package/cde-root/home/pgbovine/cat-test/cat.cde
cde-package/cde-root/home/pgbovine/cat-test/hello.txt
cde-package/cde-root/lib
cde-package/cde-root/lib/ld-linux.so.2
cde-package/cde-root/lib/ld-2.8.so
cde-package/cde-root/lib/libc.so.6
cde-package/cde-root/lib/libc-2.8.so
cde-package/cde-root/bin
cde-package/cde-root/bin/cat
cde-package/cde-root/etc
cde-package/cde-root/etc/ld.so.cache
cde-package/cde-root/usr
cde-package/cde-root/usr/lib
cde-package/cde-root/usr/lib/locale
cde-package/cde-root/usr/lib/locale/locale-archive
cde-package/cde.uname
cde-package/cde.options
cde-package/cde-exec
cde-package/cat.cde
cde-package/cde.log
cde-package/cde.full-environment

What are all of these files?

First and foremost, the cde-root/ sub-directory is a partial replica of my filesystem that contains only the files that the cat command accessed, preserving the original directory structure and symlinks. CDE uses hard links to create the replica files if possible and otherwise uses regular file copying.

In the above example, cde-package/cde-root/bin/cat is the binary executable for cat itself (a hard link to /bin/cat). Also, cde-package/cde-root/home/pgbovine/cat-test/hello.txt is the absolute path to the hello.txt file that cat took as its argument (a hard link to /home/pgbovine/cat-test/hello.txt).

These other files within cde-package/ will be used when running the cat command from within the package (see Running cde-exec to execute a package):

  • cde-exec is the program that you will invoke to execute the cat command in a sandbox within the package.
  • cde.full-environment contains the values of all the environment variables present when I executed the original cat command (from /proc/self/environ). cde-exec uses this file to set up a sandboxed environment before invoking the given command.
  • cde.options allows you to customize the behavior of cde-exec when executing commands within your package (see CDE options).
  • cde.log contains the exact set of commands that you can run within the package to replicate the original cat run.
  • cde.uname contains information about your machine (similar to what uname -a returns), which can be useful for debugging.

Packaging up multiple commands

If you run multiple terminal commands from the same working directory, then CDE will add all of their dependent files into the same cde-package/ sub-directory. As a shortcut, you can accomplish the same goal by writing a shell script that invokes all of your desired commands, and then running that shell script prepended with cde.

Running cde-exec to execute a package

To run a command from within a CDE package, you must first change into a sub-directory within cde-root/ inside of your package. (See Seamless execution mode to learn how to run packaged commands from outside of cde-root/.)

Now when you execute a command preceded by cde-exec, CDE will create a sandbox where cde-root/ becomes the root directory (i.e., /) for that command. Thus, all of that command’s requests for files will be redirected within that fake root directory (similar to a chroot jail).

cde-exec will execute the command with environment variables overridden with values from the cde-package/cde.full-environment file. In particular, this means that if a command is located within the version of $PATH in cde.full-environment, then it may be invoked by name alone without providing a full path to it.

Let’s continue with our cat example. Let’s say that I transferred my entire cde-package/ directory to my friend Bob’s computer, and he puts it in his home directory:

$ pwd
/home/bob

$ ls
cde-package/

To re-run my original cat command, Bob first needs to change into the cde-package/cde-root/home/pgbovine/cat-test directory within the package, which is a partial replica of the original directory in which I ran the cat command (/home/pgbovine/cat-test):

$ pwd
/home/bob

$ cd cde-package/cde-root/home/pgbovine/cat-test

$ pwd
/home/bob/cde-package/cde-root/home/pgbovine/cat-test

$ ls
cat.cde  hello.txt

This directory contains the original hello.txt file as well as a new file named cat.cde that did not exist in the original directory.

Bob now types this command to execute cat hello.txt within the sandbox:

$ ../../../../cde-exec cat hello.txt
hello world

The cde-exec program is located in cde-package/, so that’s why it requires a super-awkward ../../../../cde-exec relative path to invoke. For convenience, CDE has created a cat.cde shell script in that directory, which hides that awkwardly long relative path:

#!/bin/sh
../../../../cde-exec 'cat' "$@"

Thus, Bob can invoke ./cat.cde rather than the more verbose ../../../../cde-exec cat command:

$ pwd
/home/bob/cde-package/cde-root/home/pgbovine/cat-test

$ ./cat.cde hello.txt
hello world

So what is this command doing? cde-exec is executing the version of cat on the version of hello.txt from within my package. This means that if Bob’s machine didn’t have the cat program, then this command will still run fine. (Of course, this is a silly toy example, since cat exists on all Linux machines! However, CDE really shines when packaging up complex applications containing many hard-to-install dependencies.)

The cde.log file

The cde-package/cde.log file contains the exact set of commands that a user can run to replicate the original execution. In our cat example, cde.log has the following contents:

<pre> cd ‘cde-root/home/pgbovine/cat-test’ ‘./cat.cde’ ‘hello.txt’ </pre>

(The single quotes are necessary in case any commands or arguments have spaces in them.)

If Bob executes both of those commands starting from the cde-package/ directory, then he will replicate my original cat invocation on hello.txt.

Although this log file looks trivial for this simple example, it comes in handy when invoking commands with complicated command-line options. If you ran CDE multiple times with a series of commands, all of them will be logged in cde.log