X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=src%2Fceph%2Fdoc%2Frbd%2Flibvirt.rst;fp=src%2Fceph%2Fdoc%2Frbd%2Flibvirt.rst;h=f953b1f08e2303629a698b27908b8606f57c71af;hb=812ff6ca9fcd3e629e49d4328905f33eee8ca3f5;hp=0000000000000000000000000000000000000000;hpb=15280273faafb77777eab341909a3f495cf248d9;p=stor4nfv.git diff --git a/src/ceph/doc/rbd/libvirt.rst b/src/ceph/doc/rbd/libvirt.rst new file mode 100644 index 0000000..f953b1f --- /dev/null +++ b/src/ceph/doc/rbd/libvirt.rst @@ -0,0 +1,319 @@ +================================= + Using libvirt with Ceph RBD +================================= + +.. index:: Ceph Block Device; livirt + +The ``libvirt`` library creates a virtual machine abstraction layer between +hypervisor interfaces and the software applications that use them. With +``libvirt``, developers and system administrators can focus on a common +management framework, common API, and common shell interface (i.e., ``virsh``) +to many different hypervisors, including: + +- QEMU/KVM +- XEN +- LXC +- VirtualBox +- etc. + +Ceph block devices support QEMU/KVM. You can use Ceph block devices with +software that interfaces with ``libvirt``. The following stack diagram +illustrates how ``libvirt`` and QEMU use Ceph block devices via ``librbd``. + + +.. ditaa:: +---------------------------------------------------+ + | libvirt | + +------------------------+--------------------------+ + | + | configures + v + +---------------------------------------------------+ + | QEMU | + +---------------------------------------------------+ + | librbd | + +------------------------+-+------------------------+ + | OSDs | | Monitors | + +------------------------+ +------------------------+ + + +The most common ``libvirt`` use case involves providing Ceph block devices to +cloud solutions like OpenStack or CloudStack. The cloud solution uses +``libvirt`` to interact with QEMU/KVM, and QEMU/KVM interacts with Ceph block +devices via ``librbd``. See `Block Devices and OpenStack`_ and `Block Devices +and CloudStack`_ for details. See `Installation`_ for installation details. + +You can also use Ceph block devices with ``libvirt``, ``virsh`` and the +``libvirt`` API. See `libvirt Virtualization API`_ for details. + + +To create VMs that use Ceph block devices, use the procedures in the following +sections. In the exemplary embodiment, we have used ``libvirt-pool`` for the pool +name, ``client.libvirt`` for the user name, and ``new-libvirt-image`` for the +image name. You may use any value you like, but ensure you replace those values +when executing commands in the subsequent procedures. + + +Configuring Ceph +================ + +To configure Ceph for use with ``libvirt``, perform the following steps: + +#. `Create a pool`_. The following example uses the + pool name ``libvirt-pool`` with 128 placement groups. :: + + ceph osd pool create libvirt-pool 128 128 + + Verify the pool exists. :: + + ceph osd lspools + +#. Use the ``rbd`` tool to initialize the pool for use by RBD:: + + rbd pool init + +#. `Create a Ceph User`_ (or use ``client.admin`` for version 0.9.7 and + earlier). The following example uses the Ceph user name ``client.libvirt`` + and references ``libvirt-pool``. :: + + ceph auth get-or-create client.libvirt mon 'profile rbd' osd 'profile rbd pool=libvirt-pool' + + Verify the name exists. :: + + ceph auth ls + + **NOTE**: ``libvirt`` will access Ceph using the ID ``libvirt``, + not the Ceph name ``client.libvirt``. See `User Management - User`_ and + `User Management - CLI`_ for a detailed explanation of the difference + between ID and name. + +#. Use QEMU to `create an image`_ in your RBD pool. + The following example uses the image name ``new-libvirt-image`` + and references ``libvirt-pool``. :: + + qemu-img create -f rbd rbd:libvirt-pool/new-libvirt-image 2G + + Verify the image exists. :: + + rbd -p libvirt-pool ls + + **NOTE:** You can also use `rbd create`_ to create an image, but we + recommend ensuring that QEMU is working properly. + +.. tip:: Optionally, if you wish to enable debug logs and the admin socket for + this client, you can add the following section to ``/etc/ceph/ceph.conf``:: + + [client.libvirt] + log file = /var/log/ceph/qemu-guest-$pid.log + admin socket = /var/run/ceph/$cluster-$type.$id.$pid.$cctid.asok + + The ``client.libvirt`` section name should match the cephx user you created + above. If SELinux or AppArmor is enabled, note that this could prevent the + client process (qemu via libvirt) from writing the logs or admin socket to + the destination locations (``/var/log/ceph`` or ``/var/run/ceph``). + + + +Preparing the VM Manager +======================== + +You may use ``libvirt`` without a VM manager, but you may find it simpler to +create your first domain with ``virt-manager``. + +#. Install a virtual machine manager. See `KVM/VirtManager`_ for details. :: + + sudo apt-get install virt-manager + +#. Download an OS image (if necessary). + +#. Launch the virtual machine manager. :: + + sudo virt-manager + + + +Creating a VM +============= + +To create a VM with ``virt-manager``, perform the following steps: + +#. Press the **Create New Virtual Machine** button. + +#. Name the new virtual machine domain. In the exemplary embodiment, we + use the name ``libvirt-virtual-machine``. You may use any name you wish, + but ensure you replace ``libvirt-virtual-machine`` with the name you + choose in subsequent commandline and configuration examples. :: + + libvirt-virtual-machine + +#. Import the image. :: + + /path/to/image/recent-linux.img + + **NOTE:** Import a recent image. Some older images may not rescan for + virtual devices properly. + +#. Configure and start the VM. + +#. You may use ``virsh list`` to verify the VM domain exists. :: + + sudo virsh list + +#. Login to the VM (root/root) + +#. Stop the VM before configuring it for use with Ceph. + + +Configuring the VM +================== + +When configuring the VM for use with Ceph, it is important to use ``virsh`` +where appropriate. Additionally, ``virsh`` commands often require root +privileges (i.e., ``sudo``) and will not return appropriate results or notify +you that that root privileges are required. For a reference of ``virsh`` +commands, refer to `Virsh Command Reference`_. + + +#. Open the configuration file with ``virsh edit``. :: + + sudo virsh edit {vm-domain-name} + + Under ```` there should be a ```` entry. :: + + + /usr/bin/kvm + + + + +
+ + + + Replace ``/path/to/image/recent-linux.img`` with the path to the OS image. + The minimum kernel for using the faster ``virtio`` bus is 2.6.25. See + `Virtio`_ for details. + + **IMPORTANT:** Use ``sudo virsh edit`` instead of a text editor. If you edit + the configuration file under ``/etc/libvirt/qemu`` with a text editor, + ``libvirt`` may not recognize the change. If there is a discrepancy between + the contents of the XML file under ``/etc/libvirt/qemu`` and the result of + ``sudo virsh dumpxml {vm-domain-name}``, then your VM may not work + properly. + + +#. Add the Ceph RBD image you created as a ```` entry. :: + + + + + + + + + Replace ``{monitor-host}`` with the name of your host, and replace the + pool and/or image name as necessary. You may add multiple ```` + entries for your Ceph monitors. The ``dev`` attribute is the logical + device name that will appear under the ``/dev`` directory of your + VM. The optional ``bus`` attribute indicates the type of disk device to + emulate. The valid settings are driver specific (e.g., "ide", "scsi", + "virtio", "xen", "usb" or "sata"). + + See `Disks`_ for details of the ```` element, and its child elements + and attributes. + +#. Save the file. + +#. If your Ceph Storage Cluster has `Ceph Authentication`_ enabled (it does by + default), you must generate a secret. :: + + cat > secret.xml < + + client.libvirt secret + + + EOF + +#. Define the secret. :: + + sudo virsh secret-define --file secret.xml + + +#. Get the ``client.libvirt`` key and save the key string to a file. :: + + ceph auth get-key client.libvirt | sudo tee client.libvirt.key + +#. Set the UUID of the secret. :: + + sudo virsh secret-set-value --secret {uuid of secret} --base64 $(cat client.libvirt.key) && rm client.libvirt.key secret.xml + + You must also set the secret manually by adding the following ```` + entry to the ```` element you entered earlier (replacing the + ``uuid`` value with the result from the command line example above). :: + + sudo virsh edit {vm-domain-name} + + Then, add ```` element to the domain configuration file:: + + ... + + + + + `` appears + under ``/dev`` or under ``proc/partitions``. :: + + ls dev + cat proc/partitions + +If everything looks okay, you may begin using the Ceph block device +within your VM. + + +.. _Installation: ../../install +.. _libvirt Virtualization API: http://www.libvirt.org +.. _Block Devices and OpenStack: ../rbd-openstack +.. _Block Devices and CloudStack: ../rbd-cloudstack +.. _Create a pool: ../../rados/operations/pools#create-a-pool +.. _Create a Ceph User: ../../rados/operations/user-management#add-a-user +.. _create an image: ../qemu-rbd#creating-images-with-qemu +.. _Virsh Command Reference: http://www.libvirt.org/virshcmdref.html +.. _KVM/VirtManager: https://help.ubuntu.com/community/KVM/VirtManager +.. _Ceph Authentication: ../../rados/configuration/auth-config-ref +.. _Disks: http://www.libvirt.org/formatdomain.html#elementsDisks +.. _rbd create: ../rados-rbd-cmds#creating-a-block-device-image +.. _User Management - User: ../../rados/operations/user-management#user +.. _User Management - CLI: ../../rados/operations/user-management#command-line-usage +.. _Virtio: http://www.linux-kvm.org/page/Virtio