ISR

NAME

isr − Internet Suspend/Resume client program

SYNOPSIS

isr command [parcel] [−bcdDefFlpqvY] [−s server] [−u userid] [−r version] [−m vmm] [−o optstring] [−C compression] [−L count]

Commands: auth, checkin (ci), checkout (co), checkhoard, checkp, clean, deauth, dirtometer, discard, help, hoard, ls, lshoard, passwd, poweroff, resume, rmhoard, stat, sync, uuid, version

DESCRIPTION

An Internet Suspend/Resume® (ISR) system is a collection of virtual machine parcels on a server, together with a set of client hosts, each loaded with the isr client program and a virtual machine monitor. A parcel is a set of data that represents all of the state of some virtual machine in execution, and includes a keyring, a memory image, and a virtual disk. The server maintains checkpointed versions of each parcel.

Each ISR user has a unique ISR userid and a corresponding ISR password on the server. Distinct ISR userids own disjoint sets of parcels. Parcels are not shared across ISR userids. At any point in time, a parcel can be checked out on at most one client host. A simple locking mechanism enforces this policy.

The isr client program provides commands to checkout (download) parcels from the server to the client host, run parcels on the client host, checkin (upload) parcels from the client host back to the server, query the status of parcels, authenticate to the ISR system, and change the ISR password. Downloading and running a parcel is known as resuming the parcel. Locally suspending the virtual machine monitor and then uploading the parcel back to the server is known as suspending the parcel.

The isr client program also provides a command to hoard parcel state into a persistent hoard cache on the client host. A fully-hoarded parcel is one where the hoard cache contains the parcel’s entire virtual disk state; thus the parcel, once checked out, can be resumed disconnected (without a network connection). Use the lshoard command to view the state of the hoard cache on your client, and the stat command to see how much of a particular parcel is currently hoarded.

On a particular client host, the default server is given by the server variable in /usr/share/openisr/config, which may be overridden in the system config file in /etc/openisr/openisr.conf or the user config file in ~/.openisrrc. If necessary, however, the server can be specified on the command line using the -s command line option.

By default, the current ISR userid is the current Unix login name. This can be overridden by setting the userid config option in /etc/openisr/openisr.conf or ~/.openisrrc, which in turn can be overridden by specifying the -u option on the command line.

You can safely attempt to interrupt any isr command at any time by typing control-c (SIGINT). Regions of commands that should not be interrupted will ignore these SIGINT signals.

COMMANDS

isr auth

Authenticate to the ISR server. You will be prompted for your ISR password. Run this command once, at the beginning of each X session to avoid having to keep typing your ISR password.

isr checkin(ci) parcel [-b KBytes/s] [-C compression]

Checkin a parcel to the server. This command creates a new checkpointed version of the parcel on the server, and then releases a lock on the parcel so that it can be resumed by other client hosts. The -b option limits the upload bandwidth to KBytes/s. The -C option specifies the algorithm used to compress the memory image for upload; see OPTIONS below for supported values of compression.

The checkin command is idempotent, meaning that it can be safely interrupted with ctrl-c and rerun until it successfully completes.

isr checkout(co) parcel [-c] [-d] [-r oldversion]

Download a parcel from the server without running it. This command acquires a lock on the parcel and downloads the minimum amount of virtual machine state needed to run the parcel on the client host.

By default, the checkout command downloads the most recent parcel version. However, you can rollback to previous parcel versions using the -r oldversion option. Let lastversion be the most recent parcel version on the server. Then -r oldversion causes the server to first create a new version lastversion+1 that is an identical copy of version oldversion. This new version, which is now the most recent version, is then downloaded as before.

The -d option will additionally hoard the parcel after downloading it, ensuring that you will be able to resume the parcel when disconnected from the network. The -c option, when used in conjunction with the -d option, performs lengthy consistency checks on the hoard cache after hoarding has completed.

The checkout command is useful for preparing a parcel to run disconnected, but it is normally subsumed by the resume command when you are running connected. Even in connected mode, it can be useful in some situations. For example, you might want to use the stat command (which requires the parcel to be checked out) before you actually run the parcel.

isr checkp parcel [-e] [-r version] [-c] [-Y]

This is a debugging command that checks a parcel for consistency. By default, this command performs fast sanity checks on the local cache of a checked-out parcel. The -e option causes the command to check a particular version of the parcel on the server instead. By default, -e checks the most recent version, but the -r option can be used to specify a different version instead. The -c option performs an additional (and time-consuming) content consistency check on the server version (if -e is specified) or on the local cache (otherwise).

The -Y option is similar to -c, but will additionally revert any inconsistent disk chunks to their state at the most recent checkout or sync operation. This operation will only revert chunks whose data does not match the stored hash, as might result from an OpenISR or client host crash; it will not correct more exotic metadata errors. The disk image resulting from this operation will be inconsistent from the point of view of the guest operating system, but it may allow the parcel to be resumed long enough to retrieve data from the damaged disk image. (For example, if a damaged chunk contains filesystem metadata, it might be preferable for the guest operating system to read obsolete data than to receive I/O errors when trying to read the chunk.) If any chunks are reverted using this option, the local cache of the parcel will be marked as damaged and subsequent checkin attempts will be disallowed. The -Y option cannot be used with -e.

isr checkhoard [-c] [-p]

This is a maintenance command that checks the hoard cache for consistency and repairs any problems it finds. By default, this command performs fast checks on the hoard cache indexes. The -c option causes it to perform an additional (and time-consuming) content consistency check. The -p option defragments the hoard cache and resizes it to the smallest possible size.

isr clean parcel [-f]

Remove parcel from the client host and release its server lock. This command can be used as a faster alternative to checkin when you don’t need to save any of the changes you have made to parcel since the last checkout or sync.

The -f option forcibly releases the server lock, even if it is held by a different client host. That client host will be unable to checkin the parcel. This option can be useful if you’ve forgotten to checkin the parcel and want to use it from another client host.

isr deauth

Remove the authentication credentials that were established by the auth command.

isr dirtometer parcel

Launch the dirtometer for parcel, which must already be resumed. The dirtometer is a visualization tool which shows virtual disk accesses by the guest OS and the resulting parcel state.

To automatically launch the dirtometer when a parcel is resumed, pass -D to isr resume or set the dirtometer option in ~/.openisrrc.

isr discard parcel

Discard all local client changes to parcel since the last checkout or sync. This command is useful for "micro-rollbacks" that allow you to recover from mistakes during the current session. For example, if you inadvertently type "rm -rf /bin" as root in the guest, the discard command will allow you to rollback to the parcel that existed at the time of the most recent checkout or sync command.

isr help

Display a brief usage summary.

isr hoard parcel

Fetch the parcel’s entire virtual disk into the hoard cache on the client. This command fetches only the blocks that are missing on the client. You can kill it with ctrl-c and rerun it as many times as you wish without any ill effects.

You can hoard a parcel anytime and anywhere, even if other isr commands are currently running, and even if the parcel is not currently checked out on the client host.

isr ls [parcel] [-l|-L n]

List information about your parcels. By default, this command displays the status of all of the user’s parcels that are managed by the default server. The display identifies the server, and then for each parcel, prints a single line with the name, the current lock status (acquired or released), the user and client host that last changed the lock status, and the time of that change.

If a specific parcel is named on the command line, only information about that parcel will be shown. The -L option requests a long listing format, printing additional information about the n most recent parcel versions. The -l option is similar, printing information for some small default number of the most recent versions.

isr lshoard [-l]

List information about the parcels currently in the hoard cache. The -l option causes additional information to be displayed, including parcel UUIDs for passing to the rmhoard command.

isr passwd

Change your ISR password. This command does NOT change the password of the Unix login account on your client host. (Use the local passwd command for that.)

isr poweroff parcel [-m vmm] [-o optstring]

Forcibly power off a suspended parcel by deleting its memory image. When parcel is next resumed, it will perform a cold boot. This command can be used to reboot a misbehaving parcel or to recover if its memory image is damaged. The -o option will pass the optstring configuration option to the VMM. The -m option will delete the memory image for the specified vmm, rather than for the parcel’s default VMM.

isr resume parcel [-C compression] [-r oldversion] [-m vmm] [-o
optstring] [-d] [-D] [-F]

Checkout a parcel (if necessary) and then run it. Any additional state that the parcel needs while it is running, beyond that downloaded by the checkout operation, will be demand-paged from the server.

By default, the resume command requires a network connection. However, if the parcel is fully hoarded then you can use the -d option to resume disconnected. If the parcel is not fully hoarded, the -d option will remind you to run isr checkout -d to check out and hoard the parcel.

The -r option allows you to rollback to previous parcel versions, as described in the documentation for the checkout command. The -F option causes the parcel to be resumed in a window rather than in full-screen mode, which can be useful for configuring the virtual machine monitor or for running multiple parcels at once. This option may be unavailable if the VMM does not support it. The -D option launches the dirtometer, which provides a visual representation of parcel disk accesses and the resulting parcel state. The -C option specifies the algorithm used to compress newly-written disk chunks; see OPTIONS below for supported values of compression.

The -m option allows you to resume using a virtual machine monitor other than the default VMM for this parcel. This will fail if the parcel includes a memory image written by an incompatible VMM, if the VMM is not properly installed on the client host, or if the guest OS does not support the target VMM. The -o option will pass the optstring configuration option to the VMM.

isr rmhoard parcel

Remove hoarded state for parcel from the client. If parcel is currently checked out, it can be specified by name; otherwise, it must be specified by its UUID. The parcel UUID can be obtained with the lshoard -l command.

isr stat parcel

Display information about the local state of a parcel, such as the amount of state demand-paged from the server, the amount of dirty state, and the amount of state that is hoarded in the persistent hoard cache. The parcel must be checked out in order to use the stat command.

isr sync parcel [-b KBytes/s] [-C compression]

Save a new checkpointed version of parcel on the server, without releasing the lock or discarding any of the current local state. You can sync as often as you like between resume commands. The -b option limits the upload bandwidth to KBytes/s. The -C option specifies the algorithm used to compress the memory image for upload; see OPTIONS below for supported values of compression.

The sync command is idempotent, meaning that it can be safely interrupted with ctrl-c and rerun until it successfully completes.

isr uuid parcel

Display the universally unique identifier (UUID) for the specified parcel, which must be checked out.

isr version

Display the version of the ISR client.

OPTIONS

Each option has equivalent short and long forms.
-b/--bwlimit KBytes/s

Limit upload bandwidth during checkin and sync to KBytes/s.

-c/--checkstate

Perform an additional content consistency check during the checkp, checkhoard, and checkout commands.

-C/--compression compression

Override the configured compression profile, which determines how hard the ISR client should try to compress newly-generated disk chunks (at runtime) and memory images (at checkin/sync). The default is obtained from the compression option in the configuration files (see FILES below). Recognized values of compression are:
disabled

Do not compress at all. This is intended for debugging purposes only; mild will almost always perform better.

moderate

Use an algorithm which is reasonably good and reasonably fast. Choose this option for intermediate-bandwidth connections such as fast broadband.

painful

Attempt to compress as much as possible, and spend a lot of time doing it. This option is appropriate for very slow links.

Older parcels may not be configured to support all of these compression profiles; in this case, the closest match will be used.

-d/--disconnected

Resume disconnected (after hoarding), or ensure that the parcel can later be resumed disconnected.

-D/--dirtometer

Upon resume, launch the dirtometer, a visualization tool which shows virtual disk accesses by the guest OS and the resulting parcel state.

-e/--remote

For checkp, check the parcel on the server rather than on the client.

-f/--force

Cause clean to release the parcel lock on the server even if the lock is held by another client host. This will cause that client host to be unable to checkin the parcel.

-F/--no-fullscreen

When the parcel is resumed, display it in a window rather than in full-screen mode.

-l/--long

Use long listing format for the ls command, printing information about some small default number of the most recent parcel versions. For the lshoard command, show additional information about the parcels being examined.

-L/--longvers n

Use long listing format for the ls command, printing information about the n most recent parcel versions.

-m/--vmm vmm

For resume or poweroff, use a virtual machine monitor other than the parcel’s default.

-o/--vmmopt optstring

For resume or poweroff, pass the specified optstring to the virtual machine monitor. optstring can contain multiple comma-delimited options. -o can also be specified more than once.

-p/--compact

During checkhoard, defragment the hoard cache and truncate it to the minimum possible size.

-q/--quiet

Run silently (except if things go wrong).

-r/--rollback version

Optional parcel version number for the checkout, resume, and checkp commands. For checkout and resume it determines the parcel version to rollback to. For checkp it determines the parcel version to check for consistency if -e is specified.

-s/--server name

Use the server name, overriding the default. name can be a fully qualified domain name or an IP address.

-u/--user userid

By default, the current ISR userid is the current Unix login name or the value of the userid variable from the configuration files. This option overrides both of these and sets the current ISR userid to userid.

-v/--verbose

Increment the verbosity level.

-Y/--splice

For checkp on a local parcel, revert damaged chunks to their state at the most recent checkout or sync. Disallow checkin if any chunks are reverted.

EXAMPLES

Here is how you might use isr during a typical day:

After arriving at work, you login to your ISR client host. Next, you will need to authenticate to the ISR server,

$ isr auth

which prompts you for your ISR password. You are now authenticated and will not need to type this password again until you either explicitly deauth or terminate your X session.

After listing your available parcels,

$ isr ls

you decide to resume the Windows parcel called winxp in connected mode:

$ isr resume winxp

This downloads parcel winxp (if necessary) and executes it inside the virtual machine monitor (VMM).

After running the parcel all morning, you realize you need to head out to a lunch meeting in a conference room with poor wireless connectivity. So you suspend the current running parcel, which causes the VMM to return control to the Linux shell. After making sure that it is safe to run disconnected (i.e., your parcel state is hoarded),

$ isr co winxp -d

you unplug the network cable, carry your laptop to the noon meeting, and then run you parcel disconnected during the meeting:

$ isr resume winxp -d

After the meeting, you head back to the office, plug your network cable back in, and create a checkpointed version of your current parcel state on the server:

$ isr sync winxp

After running connected for the rest of the day, it’s time to head home. So you terminate the ISR session by checking in your parcel:

$ isr ci winxp

Once home, you login to your home ISR client, authenticate to the ISR server, and then checkout the parcel that you were working on at work:

$ isr resume winxp

FILES

/usr/share/openisr/config

Configuration file that specifies defaults for ISR configuration options. This file should not be modified; changes should be made in the system-wide or user-specific config files instead.

/etc/openisr/openisr.conf

Configuration file that specifies system-wide settings. Options in this file override those in /usr/share/openisr/config.

~/.openisrrc

Configuration file that specifies user-specific settings. Options in this file override those in /usr/share/openisr/config and /etc/openisr/openisr.conf.

ACKNOWLEDGMENTS

ISR was developed by Michael Kozuch and Casey Helfrich from Intel Research Pittsburgh; David O’Hallaron, Mahadev (Satya) Satyanarayanan, Matt Toups, and Benjamin Gilbert from Carnegie Mellon; and Partho Nath from Penn State. Internet Suspend/Resume and OpenISR are registered trademarks of Carnegie Mellon University.