ISR

NAME

SYNOPSIS

Commands: auth, checkin (ci), checkout (co), checkp, clean, deauth, discard, disconnect, help, hoard, ls, passwd, reset, resume, stat, sync, version

DESCRIPTION

Each ISR user has a unique ISR userid and a corresponding ISR password on the nameserver. 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 remote store to the client host, run parcels on the client host, checkin (upload) parcels from the client host back to the remote store, 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. Each parcel has its own separate hoard cache. A fully-hoarded parcel contains the entire virtual disk state in its hoard cache, and thus can be resumed disconnected, without a network connection. Use the stat command to view the state of a parcel's hoard cache on your client.

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.

On a particular client host, the default nameserver is given by the nameserver 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 ~/.openisr.conf. If necessary, however, the nameserver can be specified on the command line using the -n 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 ~/.openisr.conf, which in turn can be overridden by specifying the -u option on the command line.

COMMANDS

isr auth

Authenticate to the ISR servers. 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]

Checkin a parcel to the remote store. This command creates a new checkpointed version of the parcel in the remote store, and then releases a lock on the parcel so that it can be resumed by other client hosts. The -b KBytes/s option limits the upload bandwidth to KBytes/s.

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 [-r oldversion]

Download a parcel from the remote store without running it. The -r option allows you to rollback to previous parcel versions, as described in the documentation for the resume command. The checkout command is normally subsumed by the resume command. However, 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 [-r version] [-c]

This is a debugging command that checks a version of a parcel on the server for consistency. Checks the most recent version by default. The -c option performs an additional (and time-consuming) content consistency check.

isr clean parcel [-a]

Remove parcel from the client host and forcibly release its server lock. The -a option removes all local parcel state, including any persistent state in the parcel's hoard cache. This command can be used to release the lock on a parcel from any machine, which is handy if you've forgotten to checkin the parcel and want to use it from another machine.

isr deauth

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

isr discard parcel

Discard all local client changes to parcel since the last checkout or sync. This command can be useful for speeding up the checkin command after brief ISR sessions where you don't need to save any of the changes you made. It is also 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 disconnect parcel [-x]

Prepare the host client so that it can safely resume parcel disconnected from the network. You should always run this command before attempting to resume a parcel in disconnected mode. By default, the disconnect command is somewhat conservative, performing a lengthy internal consistency check of the hoard cache. You can skip the consistency check with the -x option.

isr help

Display a brief usage summary.

isr hoard parcel

Fetch the parcel's entire virtual disk into the parcel's 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 nameserver. The display identifies the nameserver, and then for each parcel, prints a single line with the name, the location of the content server in the remote store, 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 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 reset

This command resets the ISR runtime. If the client gets into an inconsistent state, try this command before rebooting.
  

isr resume parcel [-r oldversion] [-dX]

Checkout a parcel (if necessary) and then run 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. Any additional state that the parcel needs while it is running will be demand paged from the remote store.

By default, the resume 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 remote store. Then -r oldversion causes the remote store 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.

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. Running the disconnect or hoard commands before resuming disconnected will ensure that the parcel is fully hoarded.

The -X option is useful for configuring the virtual machine monitor, landing control in the virtual machine monitor when the the parcel is resumed and suspended.

isr stat parcel [-c]

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

isr sync parcel [-b KBytes/s]

Save a new checkpointed version of parcel in the remote store, 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 KBytes/s option limits the upload bandwidth to KBytes/s.

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

isr version

Display the version of the ISR client.

OPTIONS

-a/--allstate

Remove all parcel state, including any persistent state in the hoard cache, during the clean command.

-b/--bwlimit KBytes/s

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

-c/--checkstate

Perform an additional content consistency check during the stat and checkparcel commands.

-d/--disconnected

Resume disconnected (after hoarding).

-l/--long

Use long listing format for the ls command, printing information about some small default number of the most recent parcel versions.

-L/--longvers n

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

-n/--nameserver name

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

-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.

-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.

-x/--nocheckstate

This option speeds up the disconnect command by skipping the lengthy internal consistency check of the hoard cache.

It is provided as a debugging option to the sync and ci commands, in which case it skips the content consistency check of a parcel before and after a new version is committed to the server.

-X/--noauto

When the parcel is resumed, control lands in the virtual machine monitor instead of the parcel. This is a debugging option that is not intended for everyday use.

EXAMPLES

In the following, suppose that your Unix login name is isruser and that your ISR userid is bovik. Here is how you might use isr during a typical day:

After arriving at work, you login to your ISR client host using the Linux login name isruser and then start up X windows. Next, you will need to authenticate to the ISR servers,

isruser> 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 the X session.

After listing your available parcels,

isruser> isr ls

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

isruser> 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),

isruser> isr disconnect winxp -x

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

isruser> 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 remote store:

isruser> 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:

isruser> isr ci winxp

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

isruser> isr resume winxp

FILES

/usr/bin/isr

The ISR client program.

/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.

~/.openisr.conf

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

/usr/lib/openisr/vulpes

The user level process that demand pages state from the remote store while the parcel is running.

ACKNOWLEDGMENTS

Index

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

OPTIONS

EXAMPLES

FILES

ACKNOWLEDGMENTS