NAME

     guestfs-p2v-iso - How to build the virt-p2v disk image or CD/ISO

ABOUT THIS DOCUMENT

    This document describes how to build the virt-p2v disk image from the
    p2v-iso directory in the libguestfs sources.

    It does not describe how to use or boot virt-p2v. For that you need to
    read the virt-p2v(1) manual page. This document is only for developers.

ABOUT THE VIRT-P2V ISO

    virt-p2v converts physical machines to run on KVM. Normally you should
    not run virt-p2v directly. Instead you have to boot the physical
    machine using the bootable CD-ROM, ISO, PXE or disk image which is
    provided by this directory. The reason for this is so that virt-p2v
    runs in a "clean" environment, with no other processes running and
    modifying the disks.

    The libguestfs source directory p2v-iso contains the scripts used to
    build the bootable image.

      * It does not contain the source to virt-p2v(1). See p2v for the
      source of virt-p2v.

      * It does not contain instructions for how to run virt-p2v. For that
      you need to read the virt-p2v(1) manual page.

      * It does not build anything when you run make. This is because:

	* building the disk image takes a long time

	* you wouldn't want to rebuild it every time virt-p2v changes

	* how and what to build depends on your environment

	* for some targets, it isn't even possible to build anything
	without root permissions / a network connection / a remote service
	(like Fedora's Koji)

	* some targets require interaction, eg. inserting a USB key

      * For the same reasons as above, make check and make install in this
      directory do nothing.

    Although for historical reasons this is known as the virt-p2v "ISO", it
    may not actually build an ISO-formatted CD image. Some of the targets
    build simple disk images or USB keys.

    Although virt-p2v should be run on a physical machine, for testing
    purposes you can (and we often do) run it in a virtual machine.

    Running the virt-p2v ISO in a VM is also a legitimate way to convert a
    virtual machine from a hypervisor which is not supported by virt-v2v
    (Hyper-V is one such hypervisor).

WHICH TARGET SHOULD YOU CHOOSE?

    For a list of all targets and how to use them, see below.

    Most users should choose virt-builder-target.

    Fedora, Red Hat Enterprise Linux, CentOS and Scientific Linux users may
    wish to try the kickstart-target.

    Fedora and RHEL developers who have been given spin-livecd permission
    by the Fedora/RHEL Koji/Brew administrators may wish to try building
    the kickstart-target as a Fedora/RHEL "Spin".

virt-builder-target

    This target uses virt-builder (see virt-builder(1)) to build a bootable
    disk image or USB key containing the locally built virt-p2v binary from
    the p2v in the source.

    Use a disk image if you want to test virt-p2v inside a virtual machine.
    To use virt-p2v for real, you will need an empty USB key ≥ 6 GB in
    size. Use this target to write the USB key, which you can then plug
    into the physical machine to start the P2V process.

    Most users should use this target. It does not require any special
    permissions, but it does need network access.

    To use the virt-builder target:

      1. Choose the os-version which most closely matches your distro from
      this list:

        virt-builder -l

      2. Choose the output, which could be a file [filename] or a USB key
      [eg. /dev/sdX].

    Then run this command (from the p2v-iso directory):

     make virt-builder-target OSVERSION=fedora-20 OUTPUT=/dev/sdX

    After building the image, you can boot it directly on physical
    hardware, or for testing in qemu or KVM (see the virt-builder man page
    for example qemu and virt-install command lines).

kickstart-target

 Building the kickstart file

    Kickstart is a format used by Red Hat-derived distributions (such as
    Fedora, Red Hat Enterprise Linux, CentOS, Scientific Linux, and others)
    to describe how to make live CDs, install the distro, make "Spins" and
    so on. It is driven by a kickstart file.

    Running:

     make kickstart-target.sh REPO=... [PROXY=...]

    simply builds the kickstart file called p2v.ks.

    The variables you can specify are:

    REPO

      A list of repositories to use, eg: REPO=fedora,rawhide

    PROXY

      An optional web proxy (URL) to use for downloading packages.

    After building the kickstart file (p2v.ks) it's a good idea to check
    it.

 Locally building a live CD/ISO

    You can make a live CD on a Red Hat-derived distribution using
    livecd-creator:

     sudo livecd-creator p2v.ks

    Before running this note that you should probably run livecd-creator in
    a disposable virtual machine for these reasons:

      * You have to disable SELinux when running the tool.

      * This tool has to be run as root, and has some nasty failure modes.

      * You can only create the exact same Live CD distro as the host
      distro. Cross-builds will fail in strange ways (eg. RHBZ#1092327).

 Building a spin using Koji

    This requires spin-livecd permissions on Koji, which are not given out
    usually, even to Fedora packagers. However assuming you have been given
    these permissions (or have your own Koji instance, I guess), then you
    can do:

     koji spin-livecd [--scratch] p2v 1.XX.YY rawhide x86_64 p2v.ks

      * Add the --scratch option to do a scratch build (recommended for
      testing).

      * 1.XX.YY should match the libguestfs version

      * Instead of rawhide you can use any Koji target.

SEE ALSO

    virt-p2v(1), virt-v2v(1), virt-builder(1), livecd-creator(8),
    http://libguestfs.org/

AUTHOR

    Richard W.M. Jones

COPYRIGHT

    Copyright (C) 2009-2014 Red Hat Inc.

LICENSE

    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.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

BUGS

    To get a list of bugs against libguestfs, use this link:
    https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

    To report a new bug against libguestfs, use this link:
    https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

    When reporting a bug, please supply:

      * The version of libguestfs.

      * Where you got libguestfs (eg. which Linux distro, compiled from
      source, etc)

      * Describe the bug accurately and give a way to reproduce it.

      * Run libguestfs-test-tool(1) and paste the complete, unedited output
      into the bug report.

