Berkeley Lab Checkpoint/Restart (BLCR) Administrator's Guide

This guide describes how to install, configure, and maintain Berkeley Lab Checkpoint/Restart (BLCR) for Linux. For usage instructions please see the companion BLCR User's Guide.

1. System Requirements

BLCR consists of two kernel modules, some user-level libraries, and several command-line executables. No kernel patching is required.

BLCR has been engineered to work with a wide range of Linux kernels:

Many major vendor distributions of Linux. Those tested historically have included SuSE, RHEL (and clones such as CentOS and Scientific Linux), Fedora, Debian and Ubuntu (and this list is NOT exhaustive).
Many "vanilla" Linux 2.6.x and 3.x.y kernels (from kernel.org) have also been tested with many glibc versions (2.2 and up).
We believe vanilla versions 2.6.0 through 3.7.1 all work.
BLCR uses a set of autoconf-based feature tests to probe the kernels it builds against. It is thus likely that a custom kernel based on one of the above kernel sources will work with BLCR, provided that patches applied to the kernel don't invalidate assumptions BLCR has made.

BLCR uses assembly code to save some program state (most notably the CPU registers). This means that the BLCR kernel modules are not portable across CPU architectures "out of the box". BLCR has long supported the x86 and x86_64 architectures. The 0.6.0 release was the first to include experimental support for PowerPC64 and for ARM, while the 0.7.0 release added experimental support for 32-bit PowerPC. Currently x86 and x86_64 systems are the most fully tested with BLCR, with the other architectures tested heavily only at release time. Porting BLCR to a different CPU is not a large software effort if one has sufficient Linux kernel experience and knowledge of the target CPU's ABI and instructions. Please contact us if you are interested in contributing a port. We are especially interested in somebody with the time and equipment to complete the unfinished port to SPARC64.

2. Installing/Configuring BLCR

To build checkpoint/restart, you need the following files:

The source code for the configured kernel you are building against.
linux/version.h (a generated file from the kernel sources).
either the System.map or the vmlinux file for the kernel you are building against.
A copy of the BLCR source (blcr-X.Y.Z.tar.gz: see http://ftg.lbl.gov/checkpoint for a link to the latest version).

If you run into trouble when following the instructions below, make sure to check both our FAQ (especially the "Build/Install Questions" section), and our bug database, located at http://mantis.lbl.gov/bugzilla/. Your install problem may have already been solved!

2.1 Configuring BLCR

BLCR builds and installs much like any other autotools-based distribution:

    % tar zxf blcr-<VERSION>.tar.gz
    % cd blcr-<VERSION>
    % mkdir builddir
    % cd builddir
    % ../configure [ options ]
    % make
    % make install

Depending on which kernel you are building against, and where you wish to put the BLCR libraries, there are a number of options to configure that you need to consider. The most common of these are described in the paragraphs that follow.

We strongly recommend that you configure and build BLCR in a directory other than the one containing the BLCR source code (use of some options to configure actually require this). In the example above the build is conducted in a subdirectory, named 'builddir', of the source directory. Any writable location is fine, but you will need to invoke configure by the correct path in place of '../configure' used in the example.

If you run into issues building BLCR on your system, check the Platform-specific notes section of this document and the FAQ.

Choosing an installation directory

By default BLCR will install into /usr/local. To choose a different directory tree to install into, pass the '--prefix' flag to configure:

--prefix=[the directory you wish to install into]

However, be aware that using a location other than /usr/local or /usr may require additions to the PATH, MANPATH and LD_LIBRARY_PATH environment variables of users (more details below).

Building against a kernel other than the one that's running

By default, BLCR builds against the kernel that is running on the system at configure time, and looks in a number of standard locations for the required files that correspond to it. However, if you're building for a kernel other than the kernel that is running at the time of the build, then you'll need to pass configure one of the following two options:

--with-linux=[kernel version such as 2.6.24.3-34.fc8-i686]
--with-linux=[full path to the kernel build directory]

If no --with-linux is passed, the default is equivalent to --with-linux=`uname -r`.

Building with files in locations unknown to BLCR

In most standard installations, either the default settings or a manual --with-linux option should be enough to find all the required files. However, in some cases configure will need additional help. For instance, if the sources are not in a well known directory, the --with-linux-src=[full path] option can be used to tell configure where they are. Similarly, BLCR needs either the System.map or vmlinux files. So if neither are found in well known locations, you'll need to pass configure one of the following two options:

--with-system-map=[full path to the System.map file]
--with-vmlinux=[full path to the kernel executable]

Note that the vmlinuz file (note the final character 'z') cannot be used as a replacement for System.map or vmlinux.

Separate compilers for user-space and kernel

Historically, the Linux kernel sources have not always been kept current as gcc versions have advanced. As a result, there have been Linux distributions that have shipped two gcc versions: a current one for user-space code and an older one for compiling the kernel and kernel modules. There are also distributions that have a 64-bit kernel, but build (nearly) all of user-space as 32-bit. In that case, there might be a single gcc version installed with a default of building 32-bit objects, which therefore won't work as-is to compile the kernel modules.

In either of these cases it may be required to have BLCR build its user-space and kernel module portions with different compilers (or the same compiler with different flags). Just as most other configure-based packages, BLCR can be configured to use a specific C compiler by setting the "CC" variable at configure time. In addition, BLCR's configure honors a "KCC" variable to specify the C compiler to use for the kernel modules. For our first motivating example (a distribution with a distinct "kgcc"), you could use the following:

    % configure [ options ] KCC=kgcc

For our second motivating example (64-bit kernel with 32-bit user-space and gcc defaulting to 32-bit objects), you could use the following:

    % configure [ options ] KCC='gcc -m64'

If not set explicitly, KCC defaults to the value configure finds for CC.

Building 32-bit application support on a 64-bit platform

BLCR's build logic is capable of building both 64-bit and 32-bit libraries at the same time on most 64-bit platforms it supports. However, because this feature does not work well with certain setups, it is disabled by default. To enable it you'll want to pass configure the following option:

--enable-multilib

This option assumes "CC" generates 64-bit objects, and may instruct you to try again with the addition of an option like CC='gcc -m64' if that is not the case.

If configuration fails with this option specified, you can still configure without it to get only 64-bit application support.

BLCR does not currently support any mechanism to build 32-bit utilities and 64-bit libraries at the same time. If you want 64-bit libraries, you currently have to settle for 64-bit utilities as well.

Building static libraries (optional)

By default, BLCR does not build static versions of its libraries. If you want/need static libraries, you may enable the with:

--enable-static

However, do not pass --disable-shared unless you are certain you know what you are doing. Without the dynamic shared libraries, the cr_run utility will not function.

Building static executables (discouraged)

BLCR's utilities (cr_run, cr_checkpoint and cr_restart) are normally build with the default linker flags. This will, for most installations, result in dynamically linked executables. You may force BLCR to build statically linked utilities by passing configure the following two options:

--enable-static --enable-all-static

You might also get statically linked BLCR utilities by default if your system has no dynamic libraries installed.

If you configure with --enable-all-static (or have no dynamic libraries on your system), you should be aware that you may unknowingly be linking in the LinuxThreads implementation of pthreads, which BLCR does not support. This happens because currently many Linux distributions install the LinuxThreads static libraries in the default library search path, and the BLCR-supported NPTL libraries are installed elsewhere. If this happens to you, then configure will fail. The solution is to provide the proper "CPPFLAGS" and "LDFLAGS" when you configure BLCR. Appending something like the following to the configure command line may work:

CPPFLAGS='-I/usr/include/nptl' LDFLAGS='-L/usr/lib/nptl -L/usr/lib64/nptl'

Though you could/should leave out one of the two "LDFLAGS" options if not performing a --enable-multilib build.

Building an installable BLCR testsuite (optional)

If you pass configure the following option:

--enable-testsuite

then BLCR's tests will not only be built for testing via "make check", but will also be installed via "make install". The testsuite is installed in PREFIX/libexec/blcr-testsuite, and can be executed by running RUN_ME in that directory (once the environment variables are setup correctly).

2.2 Compiling BLCR

Just type 'make':

    % make

If you get errors, first check the FAQ and then contact us for help.

2.3 Testing your build (optional, but recommended)

As with many autotools-based packages, BLCR includes a 'check' make target. However, it cannot run the tests until the kernel modules are loaded (and will tell you so if you forget). Since the not-yet-installed kernel modules are located throughout the BLCR build directory, an 'insmod' make target is provided to automate this task. If you are not running as root, "make insmod" will try to use the 'sudo' utility to perform the insmod operations as root. However, it is not necessary (or recommended) to run the tests themselves as root. So, we recommend run the following as a non-root user if 'sudo' is installed and configured to allow your user:

    % make insmod check

Which may prompt for a password, depending on how 'sudo' is configured. If the 'sudo' utility is not installed (or not configured for your user), the following steps are equivalent:

    % su
    Password:[type root password here]
    # make insmod
    # exit
    % make check

If the modules fail to load, then your kernel may not be supported and you'll need to report this as a bug to the BLCR team, after first checking the bug database to ensure the problem isn't already known (or even fixed). Similarly, if one or more tests fail, we'll want to know that too. However, if the only failures are one or two tests that say "restart/timeout" then you should first try increasing the timeout as follows (assuming the kernel modules have already been loaded):

    % make check CRUT_TIMEOUT=120

The 'CRUT_TIMEOUT' is a value in seconds, with a default of 60 (CRUT is an acronym for Checkpoint/Restart Unit Test).

Tests marked 'SKIP' are neither a 'PASS', nor a 'FAIL' - instead they indicate a test that was not actually run. So don't be alarmed if you see one or more tests marked 'SKIP'. This happens when a given test is not applicable to your system (for instance the hugetlbfs test is skipped when no writable mountpoint for hugetlbfs is found).

Note that BLCR's testsuite intentionally tries to do "bad" things and many lines of output are expected in the system logs as a result. Do not be alarmed by them, but be prepared to provide them with any failures you report to us.

We do not advise continuing to install BLCR if any tests 'FAIL' (other than timeouts correctable by raising CRUT_TIMEOUT sufficiently).

2.4 Installing BLCR

Use the standard 'install' make target to install the BLCR utilities and libraries, and to place the kernel modules in the standard location for your kernel:

    % make install

or, if you prefer stripped binaries:

    % make install-strip

2.5 Loading the Kernel Modules

Before you can checkpoint/restart applications, the kernel modules need to be loaded into your kernel. The kernel modules are placed into a subdirectory of the lib/blcr (or lib64/blcr) branch of the installation directory. In this example, we'll assume the installation prefix was the default /usr/local and that your kernel is version 2.6.12-1.234 for an x86. Thus, for this example the kernel modules are in the directory /usr/local/lib/blcr/2.6.12-1.234/. There are two kernel modules in this directory which must be loaded (in the correct order) for BLCR to function.

As root, load the kernel modules in this order:

    # /sbin/insmod /usr/local/lib/blcr/2.6.12-1.234/blcr_imports.ko
    # /sbin/insmod /usr/local/lib/blcr/2.6.12-1.234/blcr.ko

You may wish to set up your system to load these modules by default at boot time. The exact mechanism for doing so differs between Linux distributions, and thus requires an experienced system administrator. However, a template init script is provided as etc/blcr.rc in the BLCR source directory.

2.6 Updating ld.so.cache

Nearly all Linux distributions use a caching mechanism for resolving dynamic library dependencies. If you have installed BLCR's shared library in a directory that is cached by the mechanism, then you will need to update this cache. To do so, run the ldconfig command as root; no command-line arguments are needed.

It should always be safe to run the ldconfig command, even if BLCR did not install its library in a directory managed in the cache. However, if you wish to avoid this step when unnecessary, you can know that BLCR's shared library is in a cached directory if you configured with --prefix= or --libdir= options that cause BLCR's shared library (libcr.so) to be installed in:

/lib or /usr/lib
any directory listed in /etc/ld.so.conf
any directory listed in a file under /etc/ld.so.conf.d/

Note that if you passed no --prefix= or --libdir= options to BLCR's configure script, then you should check /etc/ld.so.conf and /etc/ld.so.conf.d/ for /usr/local/lib (the default location) to determine if you actually need to run the ldconfig command.

2.7 Configuring Users' environments

Finally, you may wish to add the appropriate BLCR directories to the default PATH, LD_LIBRARY_PATH, and MANPATH environment variables for your users. You may either modify the /etc/profile and/or /etc/cshrc files, or add new files in the /etc/profile.d directory. Alternatively, you may provide modules that accomplish the same thing. You should replace PREFIX by the installation prefix (such as /usr/local) in the following examples:

For Bourne-style shells:

    $ PATH=$PATH:PREFIX/bin
    $ MANPATH=$MANPATH:PREFIX/man
    $ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:PREFIX/lib:PREFIX/lib64
    $ export PATH MANPATH LD_LIBRARY_PATH

For csh-style shells:

    % setenv PATH ${PATH}:PREFIX/bin
    % setenv MANPATH ${MANPATH}:PREFIX/man
    % setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:PREFIX/lib:PREFIX/lib64

These example assume a "multilib" system with both /lib and /lib64 directories. If your system lacks one of these two directories, the corresponding colon-separated entry may be omitted from the value of LD_LIBRARY_PATH.

It is worth noting that if the BLCR libraries are installed in a directory named in /etc/ld.so.conf or /etc/ld.so.conf.d/, then you do not need to add it to LD_LIBRARY_PATH. Similarly, you may find it unnecessary to add to PATH and/or MANPATH if BLCR has been installed in a location that is already searched.

2.8 Uninstalling BLCR

If you preserve the BLCR build tree, then there is a standard 'uninstall' make target available to remove the files copied by the 'install' target.

3. Making RPMs from the BLCR sources

An alternate way to install BLCR is to build a binary RPM for your system, which you can then install. This has certain advantages (such as making upgrading easier, especially if you maintain BLCR on multiple systems).

3.1 Building binary RPMs from the source tarball

Once you've configured BLCR with any options your system requires, the simplest method for building RPMs is to just

    % make rpms

If successful, the new RPM packages will be in the rpm/RPMS subdirectory of the build tree. The resulting packages will be for whatever kernel you configured for.

3.2 Building a binary RPM from source RPMS

You may also with start from a source RPM (with a .src.rpm suffix) rather than the .tar.gz version of the BLCR distribution. Source RPMs are available on our website. These source RPMs are configured to build for the running kernel, with --prefix=/usr and to configure with --enable-multilib on 64-bit platforms. Alternatively, the 'make rpms' step above will create a source RPM in the rpm/SRPMS subdirectory of the build tree, valid for the configured kernel.

If building as root, built RPMs will be placed in a subdirectory of /usr/src/redhat/RPMS. However, if you are not root, you may need to see this page at IBM for information on configuring an output location before proceeding. Personally, we prefer not to build as root.

To build binary RPMs from the source RPM, use

    % rpmbuild --rebuild blcr-X.Y.Z-N.src.rpm --target ARCH

replacing blcr-X.Y.Z-N.src.rpm with the correct filename, and ARCH with a specific target CPU. If you don't know your target, try "uname -p" to determine it. If you don't specify a --target, the default will depend on the version of rpmbuild and may be i386 (which will be rejected). See the documentation for rpmbuild for more information on building binary RPMs from source RPMs.

If you are on a 64-bit platform and do not wish to build the 32-bit libraries (or lack the required toolchain), then you can disable the default --enable-multilib behavior of the source RPM by adding --define 'with_multilib 0' to the rpmbuild command line.

The RPMs should build without error. However, if not building for the running kernel, you may see a warning about this. You will see the location of the binary RPMs in the last few lines of output from rpmbuild - something like this:

    Wrote: /usr/src/redhat/RPMS/i686/blcr-0.8.5-1.i686.rpm
    Wrote: /usr/src/redhat/RPMS/i686/blcr-libs-0.8.5-1.i686.rpm
    Wrote: /usr/src/redhat/RPMS/i686/blcr-devel-0.8.5-1.i686.rpm
    Wrote: /usr/src/redhat/RPMS/i686/blcr-modules_2.6.12_1.234-0.8.5-1.i686.rpm
    Wrote: /usr/src/redhat/RPMS/i686/blcr-testsuite-0.8.5-1.i686.rpm

You should note that the kernel version 2.6.12-1.234 has become 2.6.12_1.234 in the name of the blcr-modules package (a change of a hyphen to an underscore).

In most cases, you will want to install the blcr, blcr-libs and blcr-modules binary RPMS. The blcr-devel is only required on machines on which you will compiling/linking source code against BLCR's libraries. So, for a cluster you may want to install blcr-devel only on the front-end node(s).

The blcr-testsuite RPM is optional. You may install and run the testsuite (/usr/libexec/blcr-testsuite/RUN_ME) if you wish to verify correct operation of BLCR. You may be asked to do this if you report bugs to us.

4. Platform-specific notes

PowerPC (32- and 64-bit)
- There is a known problem with signal handling in some PowerPC kernel versions 2.6.15 and older that can cause restart failures with BLCR. Therefore, for effected kernels one must configure with '--with-bug2524' to enable a work-around in BLCR (with a very small performance penalty).
  If you are configuring for a kernel 2.6.15 or older on a PowerPC, BLCR's configure script will require either '--with-bug2524' or '--without-bug2524'. If you are uncertain, configure using '--with-bug2524', which is always safe. If you make an incorrect choice at configure time, then when you run 'make check' the test 'bug2524' will let you know.
ARM
- Kernel versions 2.6.11 and older lack true atomic compare-and-swap support, which BLCR require. Therefore, one must use a 2.6.12 kernel or later on ARM plarforms.

5. For more information

For more information on Berkeley Lab Checkpoint/Restart for Linux, visit the project home page: http://ftg.lbl.gov/checkpoint
To report bugs (or look for bug fixes prior to reporting new ones), visit http://mantis.lbl.gov/bugzilla