en-US/hypervisor-host-install-agent.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>

<!-- Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<section id="hypervisor-host-install-agent">
    <title>Install and configure the Agent</title>
    <para>To manage KVM instances on the host &PRODUCT; uses a Agent. This Agent communicates with the Management server and controls all the instances on the host.</para>
    <para>First we start by installing the agent:</para>
    <para>In RHEL or CentOS:</para>
    <programlisting language="Bash"><command>$ yum install cloudstack-agent</command></programlisting>
    <para>In Ubuntu:</para>
    <programlisting language="Bash"><command>$ apt-get install cloudstack-agent</command></programlisting>
    <para>The host is now ready to be added to a cluster. This is covered in a later section, see <xref linkend="host-add" />. It is recommended that you continue to read the documentation before adding the host!</para>
    <section id="config-cpu-model">
        <title>Configure CPU model for KVM guest (Optional) </title>
    <para>In additional,the &PRODUCT; Agent allows host administrator to control the guest CPU model which is exposed to KVM instances. By default, the CPU model of KVM instance is likely <emphasis role="italic"> QEMU Virtual CPU version x.x.x</emphasis> with least CPU features exposed. There are a couple of reasons to specify the CPU model:</para>
    <itemizedlist>
        <listitem><para>To maximise performance of instances by exposing new host CPU features to the KVM instances;</para>    </listitem>
        <listitem><para>To ensure a consistent default CPU across all machines,removing reliance of variable QEMU defaults;    </para> </listitem>
    </itemizedlist>
    <para> For the most part it will be sufficient for the host administrator to specify the guest CPU config in the per-host configuration file (/etc/cloudstack/agent/agent.properties). This will be achieved by introducing two new configuration parameters: </para>
    <programlisting language="Bash">guest.cpu.mode=custom|host-model|host-passthrough
guest.cpu.model=from /usr/share/libvirt/cpu_map.xml(only valid when guest.cpu.mode=custom)
    </programlisting>
    <para>There are three choices to fulfill the cpu model changes:</para>
    <orderedlist>
        <listitem>
            <para><emphasis role="bold">custom: </emphasis> you can explicitly specify one of the supported named model in /usr/share/libvirt/cpu_map.xml</para>
        </listitem>
        <listitem>
            <para><emphasis role="bold">host-model: </emphasis> libvirt will identify the CPU model in /usr/share/libvirt/cpu_map.xml which most closely matches the host, and then request additional CPU flags to complete the match. This should give close to maximum functionality/performance, which maintaining good reliability/compatibility if the guest is migrated to another host with slightly different host CPUs.  </para>
        </listitem>
        <listitem>
            <para><emphasis role="bold">host-passthrough: </emphasis> libvirt will tell KVM to passthrough the host CPU with no modifications. The difference to host-model, instead of just matching feature flags, every last detail of the host CPU is matched. This gives absolutely best performance, and can be important to some apps which check low level CPU details, but it comes at a cost with respect to migration: the guest can only be migrated to an exactly matching host CPU.  </para>
        </listitem>
    </orderedlist>
    <para>Here are some examples:</para>
    <itemizedlist>
        <listitem>
            <para>custom</para>
            <programlisting>guest.cpu.mode=custom
guest.cpu.model=SandyBridge
            </programlisting>
        </listitem>
        <listitem>
            <para>host-model</para>
            <programlisting>guest.cpu.mode=host-model </programlisting>
        </listitem>
        <listitem>
            <para>host-passthrough</para>
            <programlisting>guest.cpu.mode=host-passthrough </programlisting>
        </listitem>
    </itemizedlist>
    <note>
        <para>host-passthrough may lead to migration failure,if you have this problem,you should use host-model or custom </para>
    </note>
</section>

</section>