Provided by: care_2.2.1-1build1_amd64 
NAME
CARE - Comprehensive Archiver for Reproducible Execution
SYNOPSIS
care [option] ... command
DESCRIPTION
CARE monitors the execution of the specified command to create an archive that contains all the material
required to re-execute it in the same context. That way, the command will be reproducible everywhere,
even on Linux systems that are supposed to be not compatible with the original Linux system. CARE is
typically useful to get reliable bug reports, demonstrations, artifact evaluation, tutorials, portable
applications, minimal rootfs, file-system coverage, ...
By design, CARE does not record events at all. Instead, it archives environment variables and accessed
file-system components -- before modification -- during the so-called initial execution. Then, to
reproduce this execution, the re-execute.sh script embedded into the archive restores the environment
variables and relaunches the command confined into the saved file-system. That way, both initial and
reproduced executions should produce the same results as they use the same context, assuming they do not
rely on external events -- like key strokes or network packets -- or that these external events are
replayed manually or automatically, using umockdev for instance. That means it is possible to alter
explicitly the reproduced executions by changing content of the saved file-system, or by replaying
different external events.
Privacy
To ensure that no sensitive file can possibly leak into the archive, CARE conceals recursively the
content of $HOME and /tmp, that is, they appear empty during the original execution. Although, for
consistency reasons, the content of $PWD is revealed even if it is nested into the two previous paths.
As a consequence, a program executed under CARE may behave unexpectedly because a required path is not
accessible anymore. In this case, such a path has to be revealed explicitly. For details, see the
options --concealed-path and --revealed-path, and the file concealed-accesses.txt as well.
It is advised to inspect the archived content before sharing it.
OPTIONS
The command-line interface is composed of two parts: first CARE's options, then the command to launch.
This section describes the options supported by CARE, that is, the first part of its command-line
interface.
-o path, --output=path
Archive in path, its suffix specifies the format.
The suffix of path is used to select the archive format, it can be one of the following:
┌────────┬───────────────────────────────────────┐
│suffix │ comment │
├────────┼───────────────────────────────────────┤
│/ │ don't archive, copy into the │
│ │ specified directory instead │
├────────┼───────────────────────────────────────┤
│.tar │ most common archive format │
├────────┼───────────────────────────────────────┤
│.cpio │ most portable archive format, it can │
│ │ archive sockets too │
├────────┼───────────────────────────────────────┤
│?.gz │ most common compression format, but │
│ │ slow │
├────────┼───────────────────────────────────────┤
│?.lzo │ fast compression format, but uncommon │
└────────┴───────────────────────────────────────┘
│?.bin │ see Self-extracting format section │
├────────┼───────────────────────────────────────┤
│?.?.bin │ see Self-extracting format section │
├────────┼───────────────────────────────────────┤
│.bin │ see Self-extracting format section │
├────────┼───────────────────────────────────────┤
│.raw │ recommended archive format, use care │
│ │ -x to extract │
└────────┴───────────────────────────────────────┘
where "?" means the suffix must be combined with another one. For examples: ".tar.lzo",
".cpio.gz", ".tar.bin", ".cpio.lzo.bin", ... If this option is not specified, the default output
path is care-<DATE>.bin or care-<DATE>.raw, depending on whether CARE was built with
self-extracting format support or not.
-c path, --concealed-path=path
Make path content appear empty during the original execution.
Some paths may contain sensitive data that should never be archived. This is typically the case
for most of the files in:
• $HOME
• /tmp
That's why these directories are recursively concealed from the original execution, unless the -d
option is specified. Concealed paths appear empty during the original execution, as a consequence
their original content can't be accessed nor archived.
-r path, --revealed-path=path
Make path content accessible when nested in a concealed path.
Concealed paths might make the original execution with CARE behave differently from an execution
without CARE. For example, a lot of No such file or directory errors might appear. The solution
is to reveal recursively any required paths that would be nested into a concealed path. Note that
$PWD is revealed, unless the -d option is specified.
-p path, --volatile-path=path
Don't archive path content, reuse actual path instead.
Some paths contain only communication means with programs that can't be monitored by CARE, like
the kernel or a remote server. Such paths are said volatile; they shouldn't be archived, instead
they must be accessed from the actual rootfs during the re-execution. This is typically the case
for the following pseudo file-systems, sockets, and authority files:
• /dev
• /proc
• /sys
• /run/shm
• /tmp/.X11-unix
• /tmp/.ICE-unix
• $XAUTHORITY
• $ICEAUTHORITY
• /var/run/dbus/system_bus_socket
• /var/tmp/kdecache-$LOGNAME
This is also typically the case for any other fifos or sockets. These paths are considered
volatile, unless the -d option is specified.
-e name, --volatile-env=name
Don't archive name env. variable, reuse actual value instead.
Some environment variables are used to communicate with programs that can't be monitored by CARE,
like remote servers. Such environment variables are said volatile; they shouldn't be archived,
instead they must be accessed from the actual environment during the re-execution. This is
typically the case for the following ones:
• DISPLAY
• http_proxy
• https_proxy
• ftp_proxy
• all_proxy
• HTTP_PROXY
• HTTPS_PROXY
• FTP_PROXY
• ALL_PROXY
• DBUS_SESSION_BUS_ADDRESS
• SESSION_MANAGER
• XDG_SESSION_COOKIE
These environment variables are considered volatile, unless the -d option is specified.
-m value, --max-archivable-size=value
Set the maximum size of archivable files to value megabytes.
To keep the CPU time and the disk space used by the archiver reasonable, files whose size exceeds
value megabytes are truncated down to 0 bytes. The default is 1GB, unless the -d option is
specified. A negative value means no limit.
-d, --ignore-default-config
Don't use the default options.
-x file, --extract=file
Extract content of the archive file, then exit.
It is recommended to use this option to extract archives created by CARE because most extracting
tools -- that are not based on libarchive -- are too limited to extract them correctly.
-v value, --verbose=value
Set the level of debug information to value.
The higher the integer value is, the more detailed debug information is printed to the standard
error stream. A negative value makes CARE quiet except on fatal errors.
-V, --version, --about
Print version, copyright, license and contact, then exit.
-h, --help, --usage
Print the user manual, then exit.
EXIT STATUS
If an internal error occurs, care returns a non-zero exit status, otherwise it returns the exit status of
the last terminated program. When an error has occurred, the only way to know if it comes from the last
terminated program or from care itself is to have a look at the error message.
FILES
The output archive contains the following files:
re-execute.sh
start the re-execution of the initial command as originally specified. It is also possible to
specify an alternate command. For example, assuming gcc was archived, it can be re-invoked
differently:
$ ./re-execute.sh gcc --version gcc (Ubuntu/Linaro 4.5.2-8ubuntu4) 4.5.2
$ echo 'int main(void) { return puts("OK"); }' > rootfs/foo.c $ ./re-execute.sh gcc -Wall
/foo.c $ foo.c: In function "main": $ foo.c:1:1: warning: implicit declaration of function
"puts"
rootfs/
directory where all the files used during the original execution were archived, they will be
required for the reproduced execution.
proot virtualization tool invoked by re-execute.sh to confine the reproduced execution into the rootfs.
It also emulates the missing kernel features if needed.
concealed-accesses.txt
list of accessed paths that were concealed during the original execution. Its main purpose is to
know what are the paths that should be revealed if the the original execution didn't go as
expected. It is absolutely useless for the reproduced execution.
LIMITATIONS
It's not possible to use GDB, strace, or any programs based on ptrace under CARE yet. This latter is
also based on this syscall, but the Linux kernel allows only one ptracer per process. This will be fixed
in a future version of CARE thanks to a ptrace emulator.
EXAMPLE
In this example, Alice wants to report to Bob that the compilation of PRoot v2.4 raises an unexpected
warning:
alice$ make -C PRoot-2.4/src/
make: Entering directory `PRoot-2.4/src'
[...]
CC path/proc.o
./path/proc.c: In function 'readlink_proc':
./path/proc.c:132:3: warning: ignoring return value of 'strtol'
[...]
Technically, Alice uses Ubuntu 11.04 for x86, whereas Bob uses Slackware 13.37 on x86_64. Both distros
are supposed to be shipped with GCC 4.5.2, however Bob is not able to reproduce this issue on his system:
bob$ make -C PRoot-2.4/src/
make: Entering directory `PRoot-2.4/src'
[...]
CC path/proc.o
[...]
Since they don't have much time to investigate this issue by iterating between each other, they decide to
use CARE. First, Alice prepends care to her command:
alice$ care make -C PRoot-2.4/src/
care info: concealed path: $HOME
care info: concealed path: /tmp
care info: revealed path: $PWD
care info: ----------------------------------------------------------------------
make: Entering directory `PRoot-2.4/src'
[...]
CC path/proc.o
./path/proc.c: In function 'readlink_proc':
./path/proc.c:132:3: warning: ignoring return value of 'strtol'
[...]
care info: ----------------------------------------------------------------------
care info: Hints:
care info: - search for "conceal" in `care -h` if the execution didn't go as expected.
care info: - use `./care-130213072430.bin` to extract the output archive.
Then she sends the care-130213072430.bin file to Bob. Now, he should be able to reproduce her issue on
his system:
bob$ ./care-130213072430.bin
[...]
bob$ ./care-130213072430/re-execute.sh
make: Entering directory `PRoot-2.4/src'
[...]
CC path/proc.o
./path/proc.c: In function 'readlink_proc':
./path/proc.c:132:3: warning: ignoring return value of 'strtol'
[...]
So far so good! This compiler warning doesn't make sense to Bob since strtol is used there to check a
string format; the return value is useless, only the errno value matters. Further investigations are
required, so Bob re-execute Alice's GCC differently to get more details:
bob$ ./care-130213072430/re-execute.sh gcc --version
gcc (Ubuntu/Linaro 4.5.2-8ubuntu4) 4.5.2
Copyright (C) 2010 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
The same invocation on his system returns something slightly different:
bob$ gcc --version
gcc (GCC) 4.5.2
Copyright (C) 2010 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
This confirms that both GCC versions are the same, however Alice's one seems to have been modified by
Ubuntu. Although, according to the web page related to this Ubuntu package [1], no changes regarding
strtol were made. So Bob decides to search into the files coming from Alice's system, that is, the
rootfs directory in the archive:
bob$ grep -wIrl strtol ./care-130213072430/rootfs
care-130213072430/rootfs/usr/include/inttypes.h
care-130213072430/rootfs/usr/include/stdlib.h
[...]
Here, the file usr/include/stdlib.h contains a declaration of strtol with the "warn unused result"
attribute. On Ubuntu, this file belongs to the EGLIBC package, and its related web page [2] shows that
this attribute was actually wrongly introduced by the official EGLIBC developers. Ultimately Bob should
notify them in this regard.
Thanks to CARE, Bob was able to reproduce the issue reported by Alice without effort. For investigations
purpose, he was able to re-execute programs differently and to search into the relevant files.
[1] https://launchpad.net/ubuntu/oneiric/+source/gcc-4.5/4.5.2-8ubuntu4
[2] https://launchpad.net/ubuntu/+source/eglibc/2.13-0ubuntu13.2
SELF-EXTRACTING FORMAT
The self-extracting format used by CARE starts with an extracting program, followed by a regular archive,
and it ends with a special footer. This latter contains the signature "I_LOVE_PIZZA" followed by the
size of the embedded archive:
+------------------------+
| extracting program |
+------------------------+
| |
| embedded archive |
| |
+------------------------+
| uint8_t signature[13] |
| uint64_t archive_size | # big-endian
+------------------------+
The command care -x can be used against a self-extracting archive, even if they were not build for the
same architecture. For instance, a self-extracting archive produced for ARM can be extracted with a care
program built for x86_64, and vice versa. It is also possible to use external tools to extract the
embedded archive, for example:
$ care -o foo.tar.gz.bin /usr/bin/echo OK
[...]
OK
[...]
$ hexdump -C foo.tar.gz.bin | tail -3
0015b5b0 00 b0 2e 00 49 5f 4c 4f 56 45 5f 50 49 5a 5a 41 |....I_LOVE_PIZZA|
0015b5c0 00 00 00 00 00 00 12 b4 13 |.........|
0015b5c9
$ file_size=`stat -c %s foo.tar.gz.bin`
$ archive_size=$((16#12b413))
$ footer_size=21
$ skip=$(($file_size - $archive_size - $footer_size))
$ dd if=foo.tar.gz.bin of=foo.tar.gz bs=1 skip=$skip count=$archive_size
1225747+0 records in
1225747+0 records out
1225747 bytes (1.2 MB) copied, 2.99546 s, 409 kB/s
$ file foo.tar.gz
foo.tar.gz: gzip compressed data, from Unix
$ tar -tzf foo.tar.gz
foo/rootfs/usr/
[...]
foo/re-execute.sh
foo/README.txt
foo/proot
DOWNLOADS
CARE is heavily based on PRoot, that's why they are both hosted in the same repository:
http://github.proot.me. Since CARE is supposed to work on any Linux systems, it is recommended to use
following highly compatible static binaries:
• for x86_64: http://static.reproducible.io/care-x86_64
• for x86: http://static.reproducible.io/care-x86
• for ARM: http://static.reproducible.io/care-arm
• other architectures: on demand.
COLOPHON
Visit http://reproducible.io for help, bug reports, suggestions, patches, ... Copyright (C) 2014
STMicroelectronics, licensed under GPL v2 or later.
_____ ____ _____ ____
/ __/ __ | __ \ __|
/ /_/ | / __|
\_____|__|__|__|__\____|