diff --git a/doc/image-guide/section_centos-example.xml b/doc/image-guide/section_centos-example.xml index 772c37a9c2..9eb7aeee13 100644 --- a/doc/image-guide/section_centos-example.xml +++ b/doc/image-guide/section_centos-example.xml @@ -1,202 +1,157 @@ -
+
Example: CentOS image - We'll run through an example of installing a CentOS image. - This will focus mainly on CentOS 6.4. Because the CentOS - installation process may change across versions, if you are - using a different version of CentOS the installer steps may - differ. - + This example shows you how to install a CentOS image and focuses mainly on CentOS 6.4. + Because the CentOS installation process might differ across versions, the installation steps + might differ if you use a different version of CentOS. + Download a CentOS install ISO - - - - Navigate to the CentOS mirrors page. - - - Click one of the HTTP - links in the right-hand column next to one of - the mirrors. - - - Click the folder link of the CentOS version - you want to use. For example, - 6.4/. - - - Click the isos/ folder - link. - - - Click the x86_64/ folder - link for 64-bit images. - - - Click the ISO image you want to download. - The netinstall ISO. For example, - CentOS-6.4-x86_64-netinstall.iso - is a good choice since it's a smaller image - that will download missing packages from the - Internet during the install process. - - - - + + Navigate to the CentOS + mirrors page. + + + Click one of the HTTP links in the right-hand column next to + one of the mirrors. + + + Click the folder link of the CentOS version that you want to use. For example, + 6.4/. + + + Click the isos/ folder link. + + + Click the x86_64/ folder link for 64-bit images. + + + Click the netinstall ISO image that you want to download. For example, + CentOS-6.4-x86_64-netinstall.iso is a good choice because + it is a smaller image that downloads missing packages from the Internet during + installation. + + - Start the install process - Start the installation process using either - virt-manager or - virt-install as described in the - previous section. If using - virt-install, don't forget to connect - your VNC client to the virtual machine. - We will assume the name of your virtual machine image is - centos-6.4, which we need to know - when using virsh commands to manipulate - the state of the image. - If you're using virt-manager, the commands should look - something like - this:# qemu-img create -f qcow2 /tmp/centos-6.4.qcow2 10G + Start the installation process + Start the installation process using either virt-manager or + virt-install as described in the previous section. If you use + virt-install, do not forget to connect your VNC client to the + virtual machine. + Assume that the name of your virtual machine image is centos-6.4; + you need this name when you use virsh commands to manipulate the + state of the image. + If you use virt-manager, the commands should look something like + this: + # qemu-img create -f qcow2 /tmp/centos-6.4.qcow2 10G # virt-install --virt-type kvm --name centos-6.4 --ram 1024 \ --cdrom=/data/isos/CentOS-6.4-x86_64-netinstall.iso \ --disk /tmp/centos-6.4.qcow2,format=qcow2 \ --network network=default \ --graphics vnc,listen=0.0.0.0 --noautoconsole \ ---os-type=linux --os-variant=rhel6 +--os-type=linux --os-variant=rhel6 - Step through the install - At the initial Installer boot menu, choose the "Install - or upgrade an existing system" option. Step through the - install prompts, the defaults should be fine. + Step through the installation + At the initial Installer boot menu, choose the Install or upgrade an + existing system option. Step through the installation prompts. Accept the + defaults. - + - + Configure TCP/IP - The default TCP/IP settings are fine. In particular, - ensure that Enable IPv4 support is enabled with DHCP, - which is the default. + The default TCP/IP settings are fine. In particular, ensure that Enable IPv4 support + is enabled with DHCP, which is the default. - + - Point the installer to a CentOS web server Choose URL as the installation method. - + - Depending on the version of CentOS, the net installer - requires that the user specify either a URL, or the web - site and a CentOS directory that corresponds to one of the - CentOS mirrors. If the installer asks for a single URL, an - example of a valid URL would be: - http://mirror.umd/centos/6/os/x86_64. - Consider using other mirrors as an alternative - to mirror.umd.edu. - + Depending on the version of CentOS, the net installer requires that the user specify + either a URL or the web site and a CentOS directory that corresponds to one of the + CentOS mirrors. If the installer asks for a single URL, a valid URL might be + http://mirror.umd/centos/6/os/x86_64. + + Consider using other mirrors as an alternative to + mirror.umd.edu. + - + - - If the installer asks for web site name and CentOS - directory separately, an example would be: - - - - Web site name: - mirror.umd.edu - - - - CentOS directory: - centos/6/os/x86_64 - - - - See CentOS mirror page to get a full list of - mirrors, click on the "HTTP" link of a mirror to retrieve - the web site name of a mirror. + If the installer asks for web site name and CentOS directory separately, you might + enter: + + + Web site name: mirror.umd.edu + + + CentOS directory: centos/6/os/x86_64 + + + See CentOS mirror page to get a full list of mirrors, click on the "HTTP" link + of a mirror to retrieve the web site name of a mirror. Storage devices - If asked about what type of devices your installation - involves, choose "Basic Storage Devices". + If prompted about which type of devices your installation uses, choose Basic + Storage Devices. Hostname - The installer may ask you to choose a hostname. The - default (localhost.localdomain) is - fine. We will install the cloud-init package later, which - will set the hostname on boot when a new instance is - provisioned using this image. + The installer may ask you to choose a host name. The default + (localhost.localdomain) is fine. You install the cloud-init package later, which sets the host name on + boot when a new instance is provisioned using this image. Partition the disks - There are different options for partitioning the disks. - The default installation will use LVM partitions, and will - create three partitions (/boot, - /, swap), and this will work - fine. Alternatively, you may wish to create a single ext4 - partition, mounted to "/", should also - work fine. - If unsure, we recommend you use the installer's default - partition scheme, since there is no clear advantage to one - scheme or another. + There are different options for partitioning the disks. The default installation uses + LVM partitions, and creates three partitions (/boot, + /, swap), which works fine. Alternatively, you might want to + create a single ext4 partition that is mounted to "/", which also + works fine. + If unsure, use the default partition scheme for the installer because no scheme is + better than another. - Step through the install - Step through the install, using the default options. The - simplest thing to do is to choose the "Basic Server" - install (may be called "Server" install on older versions - of CentOS), which will install an SSH server. + Step through the installation + Step through the installation, using the default options. The simplest thing to do is + to choose the "Basic Server" install (may be called "Server" install on older versions + of CentOS), which installs an SSH server. Detach the CD-ROM and reboot - Once the install completes, you will see the screen - "Congratulations, your CentOS installation is - complete". + After the install completes, the Congratulations, your CentOS installation + is complete screen appears. - + - - To eject a disk using virsh, libvirt - requires that you attach an empty disk at the same target - that the CDROM was previously attached, which should be - hdc. You can confirm the - appropriate target using the dom dumpxml - vm-image - command. + To eject a disk by using the virsh command, libvirt requires that + you attach an empty disk at the same target that the CDROM was previously attached, + which should be hdc. You can confirm the appropriate target using the + dom dumpxml vm-image command. # virsh dumpxml centos-6.4 <domain type='kvm'> <name>centos-6.4</name> @@ -210,80 +165,64 @@ ... </domain> - Run the following commands from the host to eject the - disk and reboot using virsh, as root. If you are using - virt-manager, the commands below will work, but you can - also use the GUI to detach and reboot it by manually - stopping and - starting.# virsh attach-disk --type cdrom --mode readonly centos-6.4 "" hdc + Run the following commands from the host to eject the disk and reboot using virsh, as + root. If you are using virt-manager, the commands below will work, but you can also use + the GUI to detach and reboot it by manually stopping and starting. + # virsh attach-disk --type cdrom --mode readonly centos-6.4 "" hdc # virsh destroy centos-6.4 -# virsh start centos-6.4 +# virsh start centos-6.4 - In theory, the virsh reboot - centos-6.4 command can be used instead - of using destroy and start commands. However, in our - testing we were unable to reboot successfully using - the virsh reboot command. + In theory, you can use the virsh reboot centos-6.4 command + instead of destroy and start commands. However, in our testing we were unable to + reboot successfully using the virsh reboot command. - Log in to newly created image - When you boot for the first time after install, it may ask - you about authentication tools, you can just choose - "Exit". Then, log in as root using the root password you - specified. + When you boot for the first time after installation, you might be prompted about + authentication tools. Select Exit. Then, log in as root. Configure to fetch metadata - An instance must perform several steps on start up by - interacting with the metadata service. For example, - retrieve ssh public key and execute user data script. - There are several ways to implement this functionality, including: - - Install a cloud-init RPM, which is a port of - the Ubuntu cloud-init package. This is the - recommended approach. - - - Modify /etc/rc.local to - fetch desired information from the metadata - service, as described below. - - + An instance must interact with the metadata service to perform several tasks on start + up. For example, the instance must get the ssh public key and run the user data script. + To ensure that the instance performs these tasks, use one of these methods: + + + Install a cloud-init RPM, which is a + port of the Ubuntu cloud-init package. This is the recommended approach. + + + Modify /etc/rc.local to fetch desired information from + the metadata service, as described in the next section. + + Use cloud-init to fetch the public key - The cloud-init package will automatically fetch the - public key from the metadata server and place the key in - an account. You can install cloud-init inside the CentOS - guest by adding the EPEL - repo:# rpm -Uvh http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm -# yum install cloud-init - The account varies by distribution. On Ubuntu-based - virtual machines, the account is called "ubuntu". On - Fedora-based virtual machines, the account is called - "ec2-user". - You can change the name of the account used by - cloud-init by editing the - /etc/cloud/cloud.cfg file and - adding a line with a different user. For example, to - configure cloud-init to put the key in an account named - admin, edit the configuration file - so it has the line: + The cloud-init package automatically fetches + the public key from the metadata server and places the key in an account. You can + install cloud-init inside the CentOS guest by + adding the EPEL repo: + # rpm -Uvh http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm +# yum install cloud-init + The account varies by distribution. On Ubuntu-based virtual machines, the account is + called ubuntu. On Fedora-based virtual machines, the account is + called ec2-user. + You can change the name of the account used by cloud-init by editing the /etc/cloud/cloud.cfg + file and adding a line with a different user. For example, to configure cloud-init to put the key in an account named + admin, add this line to the configuration file: user: admin - Write a script to fetch the public key (if no - cloud-init) - If you are not able to install the cloud-init package in - your image, to fetch the ssh public key and add it to the - root account, edit the /etc/rc.local - file and add the following lines before the line - “touch - /var/lock/subsys/local” + Write a script to fetch the public key (if no cloud-init) + If you are not able to install the cloud-init + package in your image, to fetch the ssh public key and add it to the root account, edit + the /etc/rc.local file and add the following lines before the line + touch /var/lock/subsys/local: if [ ! -d /root/.ssh ]; then mkdir -p /root/.ssh chmod 700 /root/.ssh @@ -308,79 +247,69 @@ while [ ! -f /root/.ssh/authorized_keys ]; do echo "*****************" done - Some VNC clients replace : (colon) with ; - (semicolon) and _ (underscore) with - (hyphen). Make - sure it's http: not http; and authorized_keys not - authorized-keys. + Some VNC clients replace the colon (:) with a semicolon + (;) and the underscore (_) with a hyphen + (-). Make sure to specify http: and not + http;. Make sure to specify + authorized_keys and not + authorized-keys. - The above script only retrieves the ssh public key - from the metadata server. It does not retrieve - user data, - which is optional data that can be passed by the user - when requesting a new instance. User data is often - used for running a custom script when an instance - comes up. - As the OpenStack metadata service is compatible with - version 2009-04-04 of the Amazon EC2 metadata service, - consult the Amazon EC2 documentation on The previous script only gets the ssh public key from the metadata server. It does + not get user data, which is optional data that can be passed by the user when + requesting a new instance. User data is often used to run a custom script when an + instance boots. + As the OpenStack metadata service is compatible with version 2009-04-04 of the + Amazon EC2 metadata service, consult the Amazon EC2 documentation on Using Instance Metadata for details on how - to retrieve user data. + >Using Instance Metadata for details on how to get user data. Disable the zeroconf route - In order for the instance to access the metadata service, disable - the default zeroconf route: + For the instance to access the metadata service, you must disable the default zeroconf + route: # echo "NOZEROCONF=yes" >> /etc/sysconfig/network Configure console - In order for nova console-log to work - properly on CentOS 6.x, guests you may need to add the - following lines to - /boot/grub/menu.lstserial --unit=0 --speed=115200 + For the nova console-log command to work properly on CentOS + 6.x, you might need to add the following lines to the + /boot/grub/menu.lst file: + serial --unit=0 --speed=115200 terminal --timeout=10 console serial # Edit the kernel line to add the console entries -kernel ... console=tty0 console=ttyS0,115200n8 +kernel ... console=tty0 console=ttyS0,115200n8 Shut down the instance - From inside the instance, as - root:# /sbin/shutdown -h now + From inside the instance, as root: + # /sbin/shutdown -h now Clean up (remove MAC address details) - The operating system records the MAC address of the - virtual ethernet card in locations such as - /etc/sysconfig/network-scripts/ifcfg-eth0 - and - /etc/udev/rules.d/70-persistent-net.rules - during the instance process. However, each time the image - boots up, the virtual ethernet card will have a different - MAC address, so this information must be deleted from the - configuration file. - There is a utility called - virt-sysprep, that performs various - cleanup tasks such as removing the MAC address references. - It will clean up a virtual machine image in - place:# virt-sysprep -d centos-6.4 + The operating system records the MAC address of the virtual ethernet card in locations + such as /etc/sysconfig/network-scripts/ifcfg-eth0 and + /etc/udev/rules.d/70-persistent-net.rules during the instance + process. However, each time the image boots up, the virtual ethernet card will have a + different MAC address, so this information must be deleted from the configuration + file. + There is a utility called virt-sysprep, that performs various + cleanup tasks such as removing the MAC address references. It will clean up a virtual + machine image in place: + # virt-sysprep -d centos-6.4 Undefine the libvirt domain - Now that the image is ready to be uploaded to the Image - Service, you no longer need to have this virtual machine - image managed by libvirt. Use the virsh undefine - vm-image - command to inform - libvirt.# virsh undefine centos-6.4 + Now that you can upload the image to the Image Service, you no longer need to have + this virtual machine image managed by libvirt. Use the virsh undefine + vm-image command to inform libvirt: + # virsh undefine centos-6.4 Image is complete - The underlying image file you created with - qemu-img create. For example, - /tmp/centos-6.4.qcow2 is now - ready for uploading to the OpenStack Image Service. + The underlying image file that you created with qemu-img create is + ready to be uploaded. For example, you can upload the + /tmp/centos-6.4.qcow2 image to the Image Service.