en-US/about-working-with-vms.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="about-working-with-vms">
  <title>About Working with Virtual Machines</title>
  <para>&PRODUCT; provides administrators with complete control over the lifecycle of all guest VMs
    executing in the cloud. &PRODUCT; provides several guest management operations for end users and
    administrators. VMs may be stopped, started, rebooted, and destroyed.</para>
  <para>Guest VMs have a name and group. VM names and groups are opaque to &PRODUCT; and are
    available for end users to organize their VMs. Each VM can have three names for use in different
    contexts. Only two of these names can be controlled by the user:</para>
  <itemizedlist>
    <listitem>
      <para>Instance name &ndash; a unique, immutable ID that is generated by &PRODUCT; and can not
        be modified by the user. This name conforms to the requirements in IETF RFC 1123.</para>
    </listitem>
    <listitem>
      <para>Display name &ndash; the name displayed in the &PRODUCT; web UI. Can be set by the user.
        Defaults to instance name.</para>
    </listitem>
    <listitem>
      <para>Name &ndash; host name that the DHCP server assigns to the VM. Can be set by the user.
        Defaults to instance name</para>
    </listitem>
  </itemizedlist>
  <note>
    <para>You can append the display name of a guest VM to its internal name. For more information,
      see <xref linkend="append-displayname-vms"/>.</para>
  </note>
  <para>Guest VMs can be configured to be Highly Available (HA). An HA-enabled VM is monitored by
    the system. If the system detects that the VM is down, it will attempt to restart the VM,
    possibly on a different host. For more information, see HA-Enabled Virtual Machines on </para>
  <para>Each new VM is allocated one public IP address. When the VM is started, &PRODUCT;
    automatically creates a static NAT between this public IP address and the private IP address of
    the VM.</para>
  <para>If elastic IP is in use (with the NetScaler load balancer), the IP address initially
    allocated to the new VM is not marked as elastic. The user must replace the automatically
    configured IP with a specifically acquired elastic IP, and set up the static NAT mapping between
    this new IP and the guest VM’s private IP. The VM’s original IP address is then released and
    returned to the pool of available public IPs. Optionally, you can also decide not to allocate a
    public IP to a VM in an EIP-enabled Basic zone. For more information on Elastic IP, see <xref
      linkend="elastic-ip"/>.</para>
  <para>&PRODUCT; cannot distinguish a guest VM that was shut down by the user (such as with the
    “shutdown” command in Linux) from a VM that shut down unexpectedly. If an HA-enabled VM is shut
    down from inside the VM, &PRODUCT; will restart it. To shut down an HA-enabled VM, you must go
    through the &PRODUCT; UI or API.</para>
</section>