This is the OpenISR (R) system, release 0.9.7. For more information on the OpenISR system and Internet Suspend/Resume (R), please visit our website at . REQUIREMENTS ------------ To run: - Linux kernel (versions 2.6.18 through 2.6.31 supported) - Development headers for your Linux kernel version - libcurl >= 7.12.3 and curl command-line utility - zlib - libuuid from e2fsprogs - libarchive - libtasn1 - GMP - GTK+ - gtk-vnc Python bindings - Perl - Python >= 2.4 - udev - ssh - rsync - ssh-agent running in your X session (most systems provide this by default) - VirtualBox, KVM, VMware Workstation, or VMware Player - An accessible OpenISR 0.9-series server Additional requirements for the vmware driver: - On 64-bit systems: 32-bit glibc To build from a source tarball: - All of the requirements for running the OpenISR system, plus: - Development headers for glibc, libcurl, zlib, GMP, GTK+, libuuid, libtasn1, and libarchive - asn1Parser from libtasn1 - pkg-config To build from the Git repository: - All of the requirements for building the OpenISR system, plus: - Autoconf >= 2.59 - Automake >= 1.10 - libtool This release ships with an updated version of the ISR-3 server software. Future releases will include a completely new server implementation. INSTALLATION SUMMARY -------------------- ./autogen.sh # Only if building from the Git repository ./configure --sysconfdir=/etc --localstatedir=/var make make install # As root make postinst # As root Any user who will use OpenISR must be added to the "isrusers" group. VIRTUAL MACHINE MONITORS ------------------------ The OpenISR system currently includes drivers for the following virtual machine monitors. The name of the driver is listed in parentheses. - VirtualBox >= 2.0.0 (virtualbox) - KVM (kvm) - VMware Workstation and VMware Player (vmware) Newly created parcels for these VMMs require VMware Workstation 6.0 or greater, or VMware Player 2.0 or greater. Legacy parcels may work with older versions of VMware. This driver includes libvdisk, a wrapper library that is preloaded into VMware to enable support for the OpenISR virtual disk. It is installed setuid root so that it may be preloaded into the vmware-vmx executable which is itself setuid root. Due to the LD_PRELOAD rules for setuid programs, libvdisk is installed in DESTDIR/usr/lib regardless of the setting of libdir. On 64-bit systems, a 64-bit version of libvdisk is installed in DESTDIR/usr/lib64 or DESTDIR/usr/lib, depending on your Linux distribution, and a 32-bit version is installed in DESTDIR/usr/lib32 or DESTDIR/usr/lib. See the ld.so(8) man page for details on the LD_PRELOAD setuid rules. - Shell (shell) This is a stub VMM driver that merely launches a shell. It can be used for debugging, or to run a VMM for which a VMM driver does not currently exist. This driver is always built and installed unless --disable-client is specified to configure, and is not affected by the setting of --enable-vmm-drivers. - Dummy VMM (none) This is a stub VMM driver that merely waits for the invoking ISR client program to receive SIGINT, and then shuts down. It can be used by wrapper scripts to obtain access to a parcel's disk under program control. This driver is always built and installed unless --disable-client is specified to configure, and is not affected by the setting of --enable-vmm-drivers. CONFIGURE OPTIONS ----------------- Aside from the standard options, the OpenISR configure script supports the following command line options: --with-group=GROUP Overrides the name of the group which will be permitted to access the OpenISR device nodes. The default is "isrusers". --with-zlib=DIR --with-curl=DIR Specifies an additional search path for zlib or curl, respectively. In addition to the specified paths, configure will check a set of default paths for each component. --disable-client Do not build or install components that are only used by the OpenISR client. --enable-vmm-drivers= --disable-vmm-drivers List of VMM drivers to build and install, or --disable-vmm-drivers not to build any. The default is to build and install all supported VMM drivers unless --disable-client is specified, in which case no drivers are built. is a comma-separated list of VMM driver names (virtualbox, kvm, etc.). The special driver name "all" enables all supported VMM drivers. A driver name may be prefixed with the "-" character to prevent building that driver; for example, --enable-vmm-drivers=all,-vmware will build every driver except vmware. The "shell" driver is always built and installed unless --disable-client is specified, and is not affected by this option. --enable-server Build and install components that are used by the OpenISR server. CONFIGURING YOUR KERNEL ----------------------- The default kernels provided by most Linux distributions should be able to support the OpenISR kernel modules. In order to build the modules, you must have the kernel headers corresponding to your running kernel. Most distributions provide these headers in a "kernel-headers" package separate from the package containing the kernel itself. If you compile your own kernels, you must enable the following options (either built-in or as modules) in order to use the OpenISR system: - Cryptographic API (CONFIG_CRYPTO) - Architecture-optimized AES cipher, if available on your architecture (CONFIG_CRYPTO_AES_586 or CONFIG_CRYPTO_AES_X86_64) - Generic AES cipher, if no optimized version is available (CONFIG_CRYPTO_AES) - Blowfish cipher (CONFIG_CRYPTO_BLOWFISH) - SHA-1 hash, for architectures other than x86 and x86-64 (CONFIG_CRYPTO_SHA1) - CBC support, for kernels > 2.6.18 (CONFIG_CRYPTO_CBC) - Loopback block device (CONFIG_BLK_DEV_LOOP) - zlib compression (CONFIG_ZLIB_DEFLATE and CONFIG_ZLIB_INFLATE) zlib is a hidden option which cannot be selected directly from the configuration menus. The easiest way to enable it is to enable "Deflate compression algorithm" under "Cryptographic options" (CONFIG_CRYPTO_DEFLATE). INSTALLATION PATHS ------------------ By default, the OpenISR init script, udev rules, and bash completion rules are installed in subdirectories of $prefix/etc. However, most systems only look for these files in subdirectories of /etc. To solve this problem, you can pass "--sysconfdir=/etc" to configure, or you can move the files into /etc by hand. During the build process, several pieces of the OpenISR system are configured to expect helper programs and data files in the locations specified to configure. However, it is possible to install the OpenISR system to a different directory, though ISR will not work if it is run directly from there. (You might want to do this while building a binary package, for example.) To install to an alternate directory, set the DESTDIR environment variable to its absolute path when running "make install". If the vmware driver is enabled at configure time, "make install" will install the libvdisk library in the appropriate /usr/lib* directories and mark it setuid root, regardless of the installation directories specified on the configure command line. See the documentation on the vmware driver (above) for details. SUSPENDING THE HOST ------------------- It is not safe to suspend your client host system (either with suspend-to-disk or suspend-to-RAM) while a parcel is running. Host suspend may happen to work on any particular occasion, but you may encounter lockups during the suspend operation which require you to reboot the host (and which will leave the running parcel(s) in an inconsistent state). Always suspend your parcels before suspending the host. COMPONENTS AND THEIR LICENSES ----------------------------- The OpenISR system is composed of several components, licensed under several different software licenses. Here is a short summary of each component: User interface This is the "isr" command-line client, and is licensed under the Eclipse Public License, version 1.0. The code for this component can be found in the "client" directory of the source tree. Parcelkeeper This is the userspace half of the virtual disk provided by the OpenISR system to guest VMs. It is responsible for maintenance of the parcel keyring, local cache, and hoard cache; runtime communication with the server; and various maintenance tasks. Parcelkeeper is launched by the user interface code when necessary; most users will never need to start it directly. Parcelkeeper is licensed under version 2 of the GNU General Public License. Nexus This is the kernel half of the virtual disk. Nexus exports virtual block devices to userspace upon request, performs chunking and encryption, and exchanges keys with the userspace component. Nexus is licensed under version 2 of the GNU General Public License. SHA-1 Accelerator This is an assembly-language implementation of the SHA-1 hash algorithm, built as a loadable module for the Linux kernel's Cryptographic API. Implementations exist for the i586 and x86-64 architectures; the SHA-1 Accelerator will not be built on other platforms. Nexus will use the SHA-1 Accelerator to improve hashing performance if it is available; otherwise, it will use the kernel's built-in SHA-1 implementation at reduced performance. This component is licensed under version 2.1 of the GNU Lesser General Public License and can be found in the "kernel/sha1" directory of the source tree. locksrv This is the server component of the OpenISR system. It includes the programs implementing the server API, as well as a program to perform various administrative tasks. It can be found in the "locksrv" directory of the source tree, and is licensed under the Eclipse Public License, version 1.0. Miscellaneous tools The "tools" directory contains a set of command-line tools used by the client and/or server. The programs found there are licensed under the GNU General Public License, version 2. libisrcrypto This is a library containing implementations of various cryptographic algorithms. The ISR user-space components use this library to perform cryptography. It is licensed under version 2.1 of the GNU Lesser General Public License and can be found in the "crypto" subdirectory. libisrsql This is a library which provides an embedded SQL database engine. It includes an embedded copy of the third-party SQLite database library, but does not export any SQLite symbols. libisrsql is licensed under version 2 of the GNU General Public License, and can be found in the "sqlite" directory of the source tree. VMM drivers and support code These are driver programs and associated support code which allow the OpenISR client to interact with specific virtual machine monitors. They are found in the "vmm" directory of the source tree, and are licensed under the GNU General Public License, version 2. libvdisk This is a small LD_PRELOAD shim which works around VMM-enforced restrictions on the names and properties of block devices that are accessed from within a virtual machine. It is only built and installed when the vmware driver is enabled at configure time. libvdisk is found in the "libvdisk" subdirectory of the "vmm" directory, and is licensed under version 2.1 of the GNU Lesser General Public License. VirtualBox Python XPCOM bindings The Python XPCOM bindings from the VirtualBox SDK are included in the OpenISR distribution. They can be found in the "xpcom" subdirectory of the "vmm" directory and are licensed under the GNU General Public License, version 2. ACKNOWLEDGMENTS ---------------- Internet Suspend/Resume and OpenISR are registered trademarks of Carnegie Mellon University. All other trademarks are the property of their respective owners.