crtools(1)
==========
:doctype:       manpage
:man source:    CRtools
:man version:   0.0.2
:man manual:    CRtools Manual

NAME
----
crtools - checkpoint/restore in userspace

SYNOPSIS
--------
'crtools' <command> -t <pid>

DESCRIPTION
-----------
'crtools' is command line utility to steer checkpoint and restore procedure.

OPTIONS
-------
<command>::
    One of the follwong commands
        * 'dump'
                to initiate checkpoint procedure
        * 'restore'
                to restore previously checkpointed processes
        * 'show'
                to decode binary dump files and show their contents in human
                readable format
        * 'check'
                to test whether the kernel support is up-to-date
        * 'page-server'
                to launch a page server
        * 'exec'
                to execute a system call from other task\'s context

-c::
    In case of 'show' command the dumped pages content will be shown in hex format.

-D|--images-dir <path>::
    Use path 'path' as a base directory where to look for dump files set. This
    commands allpies to any <command>.

-s|--leave-stopped::
    Leave tasks in stopped state after checkpoint instead of killing them.

-f|--file <file>::
    This option is valid for 'show' command only and allows to see content of
    the <file> specified.

-x|--ext-unix-sk::
    Dump external unix sockets.

-t|--tree <pid>::
    Checkpoint the whole process tree starting from 'pid'.

-d|--restore-detached::
    Detach 'crtools' itself once restore is complete.

-n|--namespaces <ns>::
    Checkpoint namespaces. Namespaces must be separated by comma.
    Currently supported namespaces: *uts*, *ipc*, *mnt*, *pid*, *net*.

-r|--root <path>::
    Change the root filesystem (when run in mount namespace).

--evasive-devices::
    Use any path to a device file if the original one is inaccessible.

--veth-pair <IN=OUT>::
    Correspondence between outside and inside names of veth devices.

--action-script <SCR>::
    Add an external action script.
    The environment variable 'CRTOOL_SCRIPT_ACTION' contains one of the
    actions:
        * 'network-lock'
                lock network in a target network namespace

        * 'network-unlock'
                unlock network in a target network namespace

--link-remap::
    Allow to link unlinked files back when possible (modifies FS
    till restore).

-o|--log-file <file>::
    Write logging messages to 'file'.

-v <num>::
    Set logging level to 'num'. Valid options are: *0* - (silent, error messages
    only), *1* - informative (default), *2* - debug messages.

--log-pid::
    Write separate logging files per each pid.

--close <fd>::
    Close file with descriptor 'fd' before anything else.

--tcp-established::
    Checkpoint/restore established TCP connections.

-j|--shell-job::
    Allow to dump and restore shell jobs. This implies the restored task
    will inherit session and process group ID from the crtools itself.
    Also this option allows to migrate a single external tty connection, in other
    words this option allows to migrate such application as 'top' and friends.

-l|--file-locks::
    Allow to dump and restore file locks. It\'s necessary to make sure that
    all file lock users are taken into dump. So it\'s only safe to use this
    for a container dump/restore.

--ms::
    In case of *check* command does not try to check for features which are
    known to be not yet merged upstream.

--page-server::
    In case of *dump* command sends pages to a page server.

--address::
    Page server address.

--port::
    Page server port number.

-V|--version::
    Print program version.

-h|--help::
    Print inline help.

SYSCALLS EXECUTION
------------------

To run a system call from another task\'s context use

    crtools exec -t <pid> <syscall-string>

command. The syscall string should look like

    <syscall-name> <syscall-arguments>...

Each command line argument is transformed into the system call argument by
the following rules:

* If one starts with '&', the rest of it gets copied to the target task\'s
  address space and the respective syscall argument is the pointer to this
  string;

* Otherwise it\'s treated as a number (converted with strtol) and is directly
  passed into the system call.

EXAMPLES
--------

To checkpoint a program with pid '1234' and write all image files into
directory 'checkpoint' one should type

    crtools dump -D checkpoint -t 1234

To restore this program detaching crtools itself, one should type

    crtools restore -d -D checkpoint -t 1234


To close a file descriptor number '1' in task with pid '1234' run

    crtools exec -t 1234 close 1

To open a file named '/foo/bar' for read-write in the task with pid
'1234' run

    crtools exec -t 1234 open '&/foo/bar' 2


AUTHOR
------
OpenVZ team.

COPYING
-------
Copyright \(C) 2011-2012, Parallels Inc.
