en-US/update-iso-vm.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="update-iso-vm">
	<!-- CLOUDSTACK-667 -->
	<title>Changing a VM's Base Image</title>
	<para>Every VM is created from a base image, which is a template or ISO which has been created and
		stored in &PRODUCT;. Both cloud administrators and end users can create and modify templates,
		ISOs, and VMs.</para>
	<para>In &PRODUCT;, you can change an existing VM's base image from one template to another,
		or from one ISO to another. (You can not change from an ISO to a template, or from a
		template to an ISO).</para>
	<para>For example, suppose there is a
		template based on a particular operating system, and the OS vendor releases a software patch.
		The administrator or user naturally wants to apply the patch and then make sure existing VMs
		start using it. Whether a software update is involved or not, it's also possible to simply
		switch a VM from its current template to any other desired template.</para>
	<para>To change a VM's base image, call the restoreVirtualMachine API command and pass in the
		virtual machine ID and a new template ID. The template ID parameter may refer to either a
		template or an ISO, depending on which type of base image the VM was already using (it must
		match the previous type of image). When this call occurs, the VM's root disk is first destroyed,
		then a new root disk is created from the source designated in the template ID parameter. The new
		root disk is attached to the VM, and now the VM is based on the new template.</para>
	<para>You can also omit the template ID parameter from the restoreVirtualMachine call. In this
		case, the VM's root disk is destroyed and recreated, but from the same template or ISO that was
		already in use by the VM.</para>
</section>