Add .gitignore file for git.

[virt-p2v.git] / virt-p2v.1.txt

NAME
    virt-p2v - P2V (physical to virtual machine) migration tool

SUMMARY
    virt-p2v

DESCRIPTION
    virt-p2v is a live CD for migrating physical machines to virtual machine
    guests.

    In the simplest mode of operation, you take a pre-built live CD ISO from
    the main website (<http://et.redhat.com/~rjones/virt-p2v/>) and burn it
    to a CD-R. Then insert the CD-R into the physical machine which must be
    migrated, reboot, and follow the on-screen instructions. See STANDARD
    USAGE section below.

    You may also build a customized live CD. Typically this will contain
    things like server details specific to your organization, so that the
    live CD can run mostly or completely automatically. See BUILDING A
    CUSTOM LIVE CD section below.

    In both cases, files and disk images are transferred from the physical
    machine over the network to the virtualization host machine over ssh.
    Therefore "sshd" must be running on the virtualization host, and must be
    accessible to that host. See SERVER REQUIREMENTS section below.

    The "virt-p2v" script must only be run from the live CD environment. It
    isn't designed to run outside this environment and could do Bad Things
    to your machine if you try it. The script contains some checks to try to
    stop you from doing this.

    Virt-p2v does not modify the physical machine, its disks, configuration
    etc.

    USB key and PXE boot options are also available. See sections PXE
    BOOTING and BOOTING FROM A USB KEY below.

STANDARD USAGE
    After booting the live CD-R, you are presented with a series of
    questions. This section explains each question.

    Remote host
        Enter the name or IP address of the virtualization host. This is the
        host running Xen (or any other virtualization system supported by
        libvirt, eg. QEMU). This host should be accessible on the network
        and running an SSH daemon ("sshd").

    Remote port
        This is the port name or number of the SSH server on the remote
        host. The default is 22 which is the standard SSH port.

    Remote directory
        Enter the directory on the remote host where disk image(s) and
        configuration file(s) must reside.

        Note that if the remote host is running SELinux then you may not be
        able to start a Xen guest unless its disk image(s) are located in
        the default directory, "/var/lib/xen/images".

    Remote username
        Enter the remote SSH username to use to log in to the remote host.

        If you use the default username of "root" then you should ensure
        that remote root logins are enabled on the remote host (ie.
        "PermitRootLogin yes" in "/etc/ssh/sshd_config").

    Network configuration
        Choose the way that the live CD configures network access. The
        current options are:

        Automatic configuration
            In this mode, the live CD attempts to reuse the network
            configuration from the physical machine's root filesystem. You
            should probably try this method even though occasionally it does
            not work.

        Ask for fixed IP address and gateway
            In this mode the live CD will ask you for a fixed IP address and
            gateway address, and will configure your chosen interface with
            these.

        Configure from the shell
            In this mode you will be dropped into a command shell and you
            will need to issue the correct sequence of "/sbin/ifconfig"
            commands in order to configure the network interface.

            A typical sequence of commands which should bring up the network
            interface would be:

             /sbin/ifconfig eth0 AA.BB.CC.DD
             /sbin/route add default gw GG.HH.II.JJ eth0

            where "AA.BB.CC.DD" is the IP address and "GG.HH.II.JJ" is the
            gateway.

        QEMU user network
            This option configures the network for use inside a QEMU user
            network
            (<http://fabrice.bellard.free.fr/qemu/qemu-doc.html#SEC30>). It
            should only be used by developers.

    Devices
        This question lists out all local block devices (hard disk drives
        and similar) and asks you to choose which will be sent to the remote
        host. You must send at least one block device.

    Root device
        This question lists out possible root filesystems and asks you to
        choose the right one. Choose the filesystem which would normally be
        mounted as "/" on the system.

        Virt-p2v performs some autodetection and is in most cases able to
        work out which filesystems are possible root filesystems. It
        displays what it thinks is on each filesystem, but leaves it up to
        the user to make a final decision.

        The root filesystem is critical because it contains "/etc/fstab".
        This is used during P2V both to determine how other filesystems are
        normally mounted on the machine, and because this file and others
        under "/etc" may need to be modified during P2V conversion.

        If the machine has more than one root filesystem (typically because
        the machine is dual-booted with another operating system), then you
        must choose only one of them to perform the P2V conversion on.

    Hypervisor
        This question asks you to choose the hypervisor / virtualization
        system in use on the remote host.

        If you select *Xen*, *QEMU* or *KVM* then virt-p2v will produce a
        configuration file which is customized for the selected system. If
        you select *Other* then virt-p2v will produce a generic
        configuration file which will probably require hand-modification to
        work.

        See also <http://libvirt.org/format.html>.

    Machine architecture
        This question asks you to choose the machine architecture. Virt-p2v
        can normally detect this, so you should leave it as *Auto-detect*.

    Memory
        This question asks you to choose the amount of memory (RAM) in
        megabytes assigned to the virtual machine.

        If the entry is left blank, then virt-p2v will try to autodetect how
        much RAM is present in the physical machine and use that, and this
        is probably a good choice for most simple migrations.

    Virtual CPUs
        This question asks you to choose the number of virtual CPUs assigned
        to the virtual machine. Choosing 1 causes the virtual machine to be
        uniprocessor, and choosing some number greater than 1 causes the
        virtual machine to be SMP.

        If the entry is left blank, then virt-p2v will try to autodetect how
        many CPU cores are present in the physical machine and use that, and
        this is probably a good choice for most simple migrations.

    MAC address
        Here you should enter a MAC address for the virtual machine's
        emulated network card. MAC addresses are written as
        "aa:bb:cc:dd:ee:ff" where "aa", "bb" etc are hexadecimal octets.

        Leaving it blank will cause virt-p2v to choose a random MAC address
        within the "00:16:3e:.." space reserved for Xen guests. These MAC
        addresses are not tested for uniqueness so there is a very small
        chance that they could coincide, which would leave a guest unable to
        access the virtual network.

    Compression
        Choose whether to enable or disable compression on disk images as
        they are copied across the network.

        If enabled, the "-C" option is passed to ssh(1). On fast networks
        this can sometimes be slower.

        NB: The disk image is still stored uncompressed on the remote host
        however this option is set.

    Verify and proceed
        In this step you are asked to verify the settings above. If any are
        incorrect, use the *Back* button to navigate back to the setting. If
        all settings are correct, use the *OK* button to begin the P2V
        conversion.

    Network autoconfiguration
        If you selected network autoconfiguration above then virt-p2v tries
        to autoconfigure the network and ping the remote host. It then asks
        *Did automatic network configuration work?*

        You should answer "y" here if it worked.

        Answering "n" will drop you into a command shell.

        You can also switch to another virtual console if you need to
        perform additional tests. See section GETTING A SHELL below.

    SSH connection
        Unless you have set up an SSH key, or the SSH server on the remote
        host allows passwordless logins, then for each file that has to be
        transferred to the remote host you will need to confirm the identity
        of the remote host and/or enter a password.

        To understand more about this, please see the ssh(1) manual page.

  BOOTING P2V GUEST ON VIRTUALIZATION HOST
    Once the P2V conversion has been completed, and assuming it was
    successful, you will find a configuration file and one or more disk
    images on the remote host.

    The files will be located in the directory selected, usually
    "/var/lib/xen/images". The names of the files are made up of:

    "p2v-*hostname*-*YYYYMMDDHHMM*.conf" or
    "p2v-*hostname*-*YYYYMMDDHHMM*-hd*X*.img"

    To simply start up the guest, use the following commands as root:

     virsh define p2v-foo-2008MMDDHHMM.conf
     virsh start foo

    For QEMU/KVM do:

     virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf
     virsh -c qemu:///system start foo

    For other hypervisors you will need to edit the configuration file and
    read <http://libvirt.org/uri.html>.

GETTING A SHELL
    During all stages of P2V questions and conversion you can get a root
    shell on the physical machine. Use *ALT* *F2* keys to switch to the
    second virtual console, then log in as *root* with no password.

  LOG FILE
    Virt-p2v writes a detailed log file to "/tmp/virt-p2v.log". (Note that
    this "/tmp" directory is a ramdisk on the live CD, not the same as the
    "/tmp" directory of the physical machine, and more importantly it
    disappears when the machine is rebooted).

    If you are reporting a bug, please always supply this file.

SERVER REQUIREMENTS
    The virtualization host (remote host) must be running an SSH daemon
    ("sshd"), accessible from the physical machine which is being migrated.

    Previous versions of virt-p2v could use a special virt-p2v server.
    However this capability has been removed since there was practically no
    benefit.

BUILDING A CUSTOM LIVE CD
    To build a custom live CD you must download the source for virt-p2v from
    <http://et.redhat.com/~rjones/virt-p2v/> or from the Mercurial source
    repository (see website for details).

    Please read the "README" file to find the dependencies which are all in
    Fedora &gt; 8 or EPEL &gt; 5.

    The steps to creating a custom live CD are:

    1. Edit "virt-p2v" and adjust defaults
        Find the section "TO MAKE A CUSTOM virt-p2v SCRIPT ..." which is
        near to the top of this file. Edit the defaults in this section as
        detailed below.

    2. "virt-p2v --test" to verify your changes
        This command should not print anything at all. If it prints any
        message, then you will need to fix the error by going back to the
        first step.

    3. "make build" or "make update" to build a custom live CD
        "make build" will create a complete ISO from scratch. "make update"
        can be used to build a "quick" developer ISO by updating an existing
        ISO image. See section ISO ATTACHMENTS below for more details.

    4. Burn the ISO to a CD-R and test

  EDITING DEFAULTS IN THE "virt-p2v" SCRIPT
    For each default, setting it to "None" will ask the user. All of the
    defaults are set to "None" in the standard, uncustomized virt-p2v
    script, and so the standard script asks all the questions.

    You may edit "virt-p2v" and change the defaults, in which case the user
    will not be questioned. In this way you can make the script partially or
    fully automated.

    *Note about OCaml code:* "None" and "Some foo" are similar to the
    concept of a NULL pointer versus non-NULL pointer in other languages.
    This a variant type defined as:

    type α option = None | Some of α

    "greeting"
        If this is "true" then we wait for a keypress after boot and at a
        couple of other stages. If set to "false" then we try not to wait
        for any keypresses (so more automated live CDs are possible).

    "remote_host"
        Set this to "Some "hostname"" or "Some "IP-address"" to provide the
        name of the remote host.

    "remote_port"
        Set this to "Some port" (eg. "Some 22") to provide the port number
        of the remote host's SSH daemon.

    "remote_directory"
        Set this to "Some "path"" (eg. "Some "/var/lib/xen/images"") to
        provide the directory where we update P2V converted images and
        configuration files.

    "remote_username"
        Set this to "Some "username"" (eg. "Some "root"") to provide the SSH
        username to use on the remote system.

    "devices_to_send"
        Set this to a list of block devices to send to the remote system.
        For example, "Some ["sda"; "sdb"]".

    "root_filesystem"
        Set this to the name of the root filesystem.

        For a disk partition (eg. "/dev/sda1"), use:

         Some (Part ("sda", "1"))

        For a logical volume (eg. "/dev/VolGroup00/LogVol00"), use:

         Some (LV ("VolGroup00", "LogVol00"))

    "network"
        Set this to the choice for network setup. Use one of:

        "Some Auto"
            for auto-configuration

        "Some Static"
            to specify the interface, address, netmask and gateway
            statically

        "Some Shell"
            to launch a shell

        "Some QEMUUserNet"
            to use a QEMU user network (developers only)

    "static_network_config"
        This setting only applies if "network" is set to "Some Static", in
        which case you should set this to the static network settings, a
        tuple of (interface, address, netmask, gateway, nameserver):

         Some ("eth0", "192.168.2.5", "255.255.255.0", "192.168.2.1", "192.168.2.1")

    "hypervisor"
        Set this to the choice of hypervisor or virtualization system. The
        choices are: "Some Xen", "Some QEMU" or "Some KVM".

    "architecture"
        Set this to the architecture. The choices are: "Some I386" (i386 and
        up, 32 bit), "Some X86_64" (AMD and Intel x86-64, 64 bit), "Some
        IA64" (Intel IA64), "Some PPC" (PowerPC, 32 bit), "Some PPC64"
        (PowerPC, 64 bit), "Some SPARC" (Sun SPARC, 32 bit), "Some SPARC64"
        (Sun SPARC, 64 bit), "OtherArch "foo"" (a hypothetical architecture
        called *foo*), or "UnknownArch" to auto-detect the architecture.

    "memory"
        Set this to the size of memory in megabytes, eg. "Some 256". If you
        set this to "Some 0" then virt-p2v will try to autodetect the amount
        of RAM installed on the physical machine.

    "vcpus"
        Set this to the number of virtual CPUs, eg. "Some 1". If you set
        this to "Some 0" then virt-p2v will try to autodetect the number of
        CPU cores on the physical machine.

    "mac_address"
        Set this to the MAC address for the virtual network card, eg. "Some
        "aa:bb:cc:dd:ee:ff"". If you set this to "Some """ then virt-p2v
        will choose a random MAC address within the "00:16:3e:.." space
        reserved for Xen guests. These MAC addresses are not tested for
        uniqueness so there is a very small chance that they could coincide,
        which would leave a guest unable to access the virtual network.

    "compression"
        Set this to "Some false" to disable compression, or "Some true" to
        enable compression, or "None" to ask the user.

  ISO ATTACHMENTS
    Rebuilding a custom ISO is time-consuming. You can make a "quick"
    developer ISO by updating an existing ISO image with a new custom
    "virt-p2v" script. This is useful for testing purposes.

    From the source directory, assuming that you have downloaded or built an
    existing "virt-p2v-*.iso", you can just do:

     make update

    or the equivalent manual command:

     ./iso-attach virt-p2v-VERSION.iso virt-p2v

    Note that ISO attachments only work with real (and emulated) CD-Rs, not
    with other methods of booting such as USB keys and PXE.

PXE BOOTING
    If you wish to boot over the network using PXE, use the
    "livecd-iso-to-pxeboot" script (part of "livecd-tools").

     livecd-iso-to-pxeboot virt-p2v-$VERSION.iso

    then copy the generated subdirectory "tftpboot/" to the right place for
    your PXE configuration.

    Pre-built PXE boot images are also available on the website.

    General configuration of DHCP, TFTP and PXE for network booting are
    outside the scope of this document.

BOOTING FROM A USB KEY
    If you wish to boot from a USB keydrive, use the "livecd-iso-to-disk"
    script (part of "livecd-tools"):

     livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1

    (Replace /dev/sdX1 with the actual USB device).

    In my experience I also had to set up a suitable MBR:

     cat /usr/lib/syslinux/mbr.bin > /dev/sdX

TESTING AN ISO UNDER QEMU OR KVM
    If you have a virtual guest running under QEMU or KVM then you can test
    the P2V conversion process on the guest.

    (Technically this is a V2V -- virtual to virtual -- conversion).

    From the source directory do:

     make boot HDA=qemuimage.img

    where "qemuimage.img" is the name of the QEMU/KVM image.

    You can also supply an "HDB" parameter to specify a second disk.

MAILING LIST
    Please direct questions to the et-mgmt-tools mailing list
    <http://www.redhat.com/mailman/listinfo/et-mgmt-tools> <et-mgmt-tools @
    redhat . com>

SEE ALSO
    virsh(1), <http://www.libvirt.org/ocaml/>, <http://www.libvirt.org/>,
    <http://et.redhat.com/~rjones/>, <http://caml.inria.fr/>

AUTHORS
    Richard W.M. Jones <rjones @ redhat . com>

COPYRIGHT
    (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
    http://libvirt.org/

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    675 Mass Ave, Cambridge, MA 02139, USA.

REPORTING BUGS
    Bugs can be viewed on the Red Hat Bugzilla page:
    <https://bugzilla.redhat.com/>.

    If you find a bug in virt-p2v, please follow these steps to report it:

    1. Check for existing bug reports
        Go to <https://bugzilla.redhat.com/> and search for similar bugs.
        Someone may already have reported the same bug, and they may even
        have fixed it.

    2. Capture debug and error messages
        At the point where you get the error or unexpected behaviour, go to
        the second virtual console (*ALT* *F2*) and look at the logfile
        "/tmp/virt-p2v.log". Please make sure that this file is attached to
        your bug report.

    3. Get version of virt-p2v
        The version is in the name of the ISO. If you have built a custom
        virt-p2v ISO, please describe any changes that you have made.

    4. Submit a bug report.
        Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
        describe the problem in as much detail as possible.

        Remember to include the version number (step 3) and to attach the
        log file (step 2).

    5. Assign the bug to rjones @ redhat.com
        Assign or reassign the bug to rjones @ redhat.com (without the
        spaces). You can also send me an email with the bug number if you
        want a faster response.