Updated Branches: refs/heads/master 351cf1a8c -> 0c4396963
CLOUDSTACK-4329: Added Linux Template Creation Signed-off-by: Marty Sweet <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/0c439696 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/0c439696 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/0c439696 Branch: refs/heads/master Commit: 0c439696301dc6a776b085b580f12ca6f054f0b0 Parents: 351cf1a Author: Marty Sweet <[email protected]> Authored: Sun Dec 8 15:28:25 2013 +0000 Committer: Sebastien Goasguen <[email protected]> Committed: Mon Dec 9 12:32:08 2013 +0100 ---------------------------------------------------------------------- en-US/create-linux-template.xml | 41 ++++++++ en-US/prepare-linux-template.xml | 190 ++++++++++++++++++++++++++++++++++ en-US/working-with-templates.xml | 1 + 3 files changed, 232 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/0c439696/en-US/create-linux-template.xml ---------------------------------------------------------------------- diff --git a/en-US/create-linux-template.xml b/en-US/create-linux-template.xml new file mode 100755 index 0000000..156a0ac --- /dev/null +++ b/en-US/create-linux-template.xml @@ -0,0 +1,41 @@ +<?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. +--> + +<!-- Please keep the doctype and license declarations above intact in each doc file. --> +<!-- Make your modifications below this line. --> + +<section id="create-linux-template"> + <title>Creating a Linux Template</title> + <para>Linux templates should be prepared using this documentation in order to prepare your linux VMs for template deployment. For ease of documentation, the VM which you are configuring the template on will be referred to as "Template Master". This guide currently covers legacy setups which do not take advantage of UserData and cloud-init and assumes openssh-server is installed during installation. + </para> + + <para>An overview of the procedure is as follow:</para> + <orderedlist> + <listitem><para>Upload your Linux ISO.</para> <para>For more information, see <xref linkend="add-iso"/>.</para></listitem> + <listitem><para>Create a VM Instance with this ISO.</para><para> For more information, see <xref linkend="creating-vms"/>.</para></listitem> + <listitem><para>Prepare the Linux VM</para></listitem> + <listitem><para>Create a template from the VM.</para><para> For more information, see <xref linkend="create-template-from-existing-vm"/>.</para></listitem> + </orderedlist> + + <xi:include href="prepare-linux-template.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + </section> + http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/0c439696/en-US/prepare-linux-template.xml ---------------------------------------------------------------------- diff --git a/en-US/prepare-linux-template.xml b/en-US/prepare-linux-template.xml new file mode 100755 index 0000000..84c2cde --- /dev/null +++ b/en-US/prepare-linux-template.xml @@ -0,0 +1,190 @@ +<?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="prepare-linux-template"> + <title>System preparation for Linux</title> + <para>The following steps will prepare a basic Linux installation for templating.</para> + + <orderedlist> + <listitem> + <para><emphasis role="bold">Installation</emphasis></para> + <para>It is good practice to name your VM something generic during installation, this will ensure components such as LVM do not appear unique to a machine. It is recommended that the name of "localhost" is used for installation.</para> + <warning><para>For CentOS, it is necessary to take unique identification out of the interface configuration file, for this edit /etc/sysconfig/network-scripts/ifcfg-eth0 and change the content to the following.</para> + <programlisting> + DEVICE=eth0 + TYPE=Ethernet + BOOTPROTO=dhcp + ONBOOT=yes + </programlisting> + </warning> + <para>The next steps updates the packages on the Template Master.</para> + <itemizedlist> + <listitem> + <para>Ubuntu</para> + <programlisting> + sudo -i + apt-get update + apt-get upgrade -y + apt-get install -y acpid ntp + reboot + </programlisting> + </listitem> + <listitem> + <para>CentOS</para> + <programlisting> + ifup eth0 + yum update -y + reboot + </programlisting> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para><emphasis role="bold">Password management</emphasis></para> + <note><para>If preferred, custom users (such as ones created during the Ubuntu installation) should be removed. First ensure the root user account is enabled by giving it a password and then login as root to continue.</para> + <programlisting> + sudo passwd root + logout + </programlisting> + <para>As root, remove any custom user accounts created during the installation process.</para> + <programlisting> + deluser myuser --remove-home + </programlisting> + </note> + <para>See <xref linkend="add-password-management-to-templates"/> for instructions to setup the password management script, this will allow &PRODUCT; to change your root password from the web interface.</para> + </listitem> + <listitem> + <para><emphasis role="bold">Hostname Management</emphasis></para> + <para>CentOS configures the hostname by default on boot. Unfortunately Ubuntu does not have this functionality, for Ubuntu installations use the following steps.</para> + <itemizedlist> + <listitem> + <para>Ubuntu</para> + <para>The hostname of a Templated VM is set by a custom script in /etc/dhcp/dhclient-exit-hooks.d, this script first checks if the current hostname is localhost, if true, it will get the host-name, domain-name and fixed-ip from the DHCP lease file and use those values to set the hostname and append the /etc/hosts file for local hostname resolution. Once this script, or a user has changed the hostname from localhost, it will no longer adjust system files regardless of it's new hostname. The script also recreates openssh-server keys, which should have been deleted before templating (shown below). Save the following script to /etc/dhcp/dhclient-exit-hooks.d/sethostname, and adjust the permissions. + </para> + <programlisting> + #!/bin/sh + # dhclient change hostname script for Ubuntu + oldhostname=$(hostname -s) + if [ $oldhostname = 'localhost' ] + then + sleep 10 # Wait for configuration to be written to disk + hostname=$(cat /var/lib/dhcp/dhclient.eth0.leases | awk ' /host-name/ { host = $3 } END { printf host } ' | sed 's/[";]//g' ) + fqdn="$hostname.$(cat /var/lib/dhcp/dhclient.eth0.leases | awk ' /domain-name/ { domain = $3 } END { printf domain } ' | sed 's/[";]//g')" + ip=$(cat /var/lib/dhcp/dhclient.eth0.leases | awk ' /fixed-address/ { lease = $2 } END { printf lease } ' | sed 's/[";]//g') + echo "cloudstack-hostname: Hostname _localhost_ detected. Changing hostname and adding hosts." + echo " Hostname: $hostname \n FQDN: $fqdn \n IP: $ip" + # Update /etc/hosts + awk -v i="$ip" -v f="$fqdn" -v h="$hostname" "/^127/{x=1} !/^127/ && x { x=0; print i,f,h; } { print $0; }" /etc/hosts > /etc/hosts.dhcp.tmp + mv /etc/hosts /etc/hosts.dhcp.bak + mv /etc/hosts.dhcp.tmp /etc/hosts + # Rename Host + echo $hostname > /etc/hostname + hostname $hostname + # Recreate SSH2 + dpkg-reconfig openssh-server + fi + ### End of Script ### + + chmod 774 /etc/dhcp/dhclient-exit-hooks.d/sethostname + </programlisting> + </listitem> + </itemizedlist> + + <warning><para>The following steps should be run when you are ready to template your Template Master. If the Template Master is rebooted during these steps you will have to run all the steps again. At the end of this process the Template Master should be shutdown and the template created in order to create and deploy the final template.</para></warning> + </listitem> + <listitem> + <para><emphasis role="bold">Remove the udev persistent device rules</emphasis></para> + <para>This step removes information unique to your Template Master such as network MAC addresses, lease files and CD block devices, the files are automatically generated on next boot.</para> + <itemizedlist> + <listitem> + <para>Ubuntu</para> + <programlisting> + rm -f /etc/udev/rules.d/70* + rm -f /var/lib/dhcp/dhclient.* + </programlisting> + </listitem> + <listitem> + <para>CentOS</para> + <programlisting> + rm -f /etc/udev/rules.d/70* + rm -f /var/lib/dhclient/* + </programlisting> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para><emphasis role="bold">Remove SSH Keys</emphasis></para> + <para>This step is to ensure all your Templated VMs do not have the same SSH keys, which would decrease the security of the machines dramatically.</para> + <programlisting> + rm -f /etc/ssh/*key* + </programlisting> + </listitem> + <listitem> + <para><emphasis role="bold">Cleaning log files</emphasis></para> + <para>It is good practice to remove old logs from the Template Master.</para> + <programlisting> + cat /dev/null > /var/log/audit/audit.log 2>/dev/null + cat /dev/null > /var/log/wtmp 2>/dev/null + logrotate -f /etc/logrotate.conf 2>/dev/null + rm -f /var/log/*-* /var/log/*.gz 2>/dev/null + </programlisting> + </listitem> + <listitem> + <para><emphasis role="bold">Setting hostname</emphasis></para> + <para>In order for the Ubuntu DHCP script to function and the CentOS dhclient to set the VM hostname they both require the Template Master's hostname to be "localhost", run the following commands to change the hostname.</para> + <programlisting> + hostname localhost + echo "localhost" > /etc/hostname + </programlisting> + </listitem> + <listitem> + <para><emphasis role="bold">Set user password to expire</emphasis></para> + <para>This step forces the user to change the password of the VM after the template has been deployed.</para> + <programlisting> + passwd --expire root + </programlisting> + </listitem> + <listitem> + <para><emphasis role="bold">Clearing User History</emphasis></para> + <para>The next step clears the bash commands you have just run.</para> + <programlisting> + history -c + unset HISTFILE + </programlisting> + </listitem> + <listitem> + <para><emphasis role="bold">Shutdown the VM</emphasis></para> + <para>Your now ready to shutdown your Template Master and create a template!</para> + <programlisting> + halt -p + </programlisting> + </listitem> + <listitem> + <para><emphasis role="bold">Create the template!</emphasis></para> + <para>You are now ready to create the template, for more information see <xref linkend="create-template-from-existing-vm"/>.</para> + </listitem> + </orderedlist> + <note><para>Templated VMs for both Ubuntu and CentOS may require a reboot after provisioning in order to pickup the hostname.</para></note> + + +</section> http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/0c439696/en-US/working-with-templates.xml ---------------------------------------------------------------------- diff --git a/en-US/working-with-templates.xml b/en-US/working-with-templates.xml index 9f4e750..062bdfa 100644 --- a/en-US/working-with-templates.xml +++ b/en-US/working-with-templates.xml @@ -36,6 +36,7 @@ <xi:include href="create-template-from-snapshot.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="upload-template.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="export-template.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="create-linux-template.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="create-windows-template.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="import-ami.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="convert-hyperv-vm-to-template.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; />
