diff --git a/.gitignore b/.gitignore index b25c15b..93bfd12 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ *~ +.DS_Store diff --git a/README.md b/README.md index be88c3d..e35b728 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ availability zone. ### Creating OpenStack images for Nectar -The [q-image-create](openstack-images/q-image-create.md) script can +The [q-image-maker](openstack-images/q-image-maker.md) script can assist with the process of creating a virtual machine images for Nectar. @@ -31,7 +31,9 @@ For example, if you want to instantiate a virtual machine instance with a different operating system: one that someone else has not created a Nectar image for you to use. -It has been tested with Linux and Windows images. +It has been used to create Linux and Windows images. + +See the [openstack-images](tree/master/openstack-images) folder for details. Licence ------- diff --git a/openstack-images/README-init.md b/openstack-images/README-init.md index 6cc63b1..358d392 100644 --- a/openstack-images/README-init.md +++ b/openstack-images/README-init.md @@ -30,13 +30,21 @@ script). Therefore, the creation host needs to be larger than that. ### Step 2: Install necessary packages -The QEMU hypervisor is needed to create the image, and the OpenStack -client (in particular the _glance_ component) is needed to upload the -image. +The following packages are required: -Login to the creation host system and install those packages. The -following commands are for CentOS 7, different commands will be needed -for other distributions: +- QEMU hypervisor is needed to create the image; and + +- the OpenStackclient (in particular the _glance_ component) is needed +to upload the image. + +Login to the creation host system and install those packages. + +The steps to install them will be different for different Linux +distributions, and there are different approaches that can be taken. +For example, the OpenStack client tools can be installed from a +repository, or installed as Python packages (either installed into the +system or in a Python virtual environment). Some example installation +steps are shown below. CentOS 7: @@ -51,6 +59,32 @@ CentOS 7: [ec2-user@host]$ sudo pip3 install python-openstackclient +CentOS 8 Stream: + +**Note: currently the process does not work properly on CentOS 8 and +CentOS 8 Stream. Everything works except the guest VM cannot connect +to the Internet. So please use one of the other distributions until +this problem is solved.** + +The same as for CentOS 7, except there might be an error saying: +_Cannot uninstall 'PyYAML'. It is a distutils installed project and +thus we cannot accurately determine which files belong to it which +would lead to only a partial uninstall._ + +If that error occurs, run the following to install PyYAML + + [ec2-user@host]$ sudo pip3 install --ignore-installed PyYAML + +And then run the _pip install_ for _python-openstackclient_. Without +the _--ignore-installed_ option, _pip_ attempts to uninstall the old +version of the package before installing the new version. But that +fails, as the error message says, because it does not know how to +properly uninstall the old version. The option tells _pip_ to install +the new version over the old version, without first uninstalling it. +There are probably other ways around this too, such as uninstalling +PyYAML first or installing the OpenStack client in a Python virtual +environment. + Ubuntu 20.04: [local]$ ssh ec2-user@creation.host.system @@ -96,5 +130,5 @@ Log out of the creation host. See also -------- -- [Creating an image for CentOS Stream 8](image-linux.md) -- [Creating an image for Windows Server 2012 R2](image-windows.md) +- [Creating an image for Linux](README-linux.md) +- [Creating an image for Microsoft Windows](README-windows.md) diff --git a/openstack-images/README-linux.md b/openstack-images/README-linux.md index 221f01c..4e5c694 100644 --- a/openstack-images/README-linux.md +++ b/openstack-images/README-linux.md @@ -16,7 +16,7 @@ Requirements - OpenStack project to upload the image to. - Local system, with a ssh client and a VNC client. -- Creation host system, with QEMU and glance (e.g. a [configured VM instance](image-init.md)). +- Creation host system, with QEMU and glance (e.g. a [configured VM instance](README-init.md)). - Installation ISO image for the CentOS Stream 8. Process @@ -324,7 +324,7 @@ accessed by typing Ctrl-Alt-2 into the VNC client). If additional configuration needs to be performed, restart the guest virtual machine by booting off the disk image. - $ ./q-image-maker.sh --run disk.qcow2 + $ ./q-image-maker.sh run disk.qcow2 As before, connect to the VNC server (through the ssh tunnel) with an empty password. @@ -395,4 +395,4 @@ Future work Contact ------- -Please send feedback and queries to Hoylen Sue at . +Please send feedback and queries to Hoylen Sue at . diff --git a/openstack-images/README-windows.md b/openstack-images/README-windows.md index 5ba072e..ef1f271 100644 --- a/openstack-images/README-windows.md +++ b/openstack-images/README-windows.md @@ -11,7 +11,7 @@ Requirements ------------ - Local machine, with a ssh client and a VNC client. -- Creation host, with QEMU and the OpenStack client (e.g. a [configured VM instance](image-init.md)). +- Creation host, with QEMU and the OpenStack client (e.g. a [configured VM instance](README-init.md)). - Installation ISO image for Microsoft Windows Server 2020. - VirtIO drivers for Windows ISO image. - Suitable licence for Microsoft Windows Server 2020 (optinal for testing). @@ -119,11 +119,14 @@ size as the disk on the virtual machine that will be instantiated. The disk image will be in the default QEMU Copy-On-Write version 2 "qcow2" format, which is required for it to be used as the boot disk. If the image will be used on volume storage, the "raw" format -needs to be used. +needs to be used. Use the `--format` option to set the format; use the +`--help` option or read the [q-image-maker +manual](https://github.com/qcif/cloud-utils/blob/master/openstack-images/q-image-maker.md) +(a Markdown file from the GitHub repository) for details. The VNC server is listening by default on display 0 (port 5900). Use a different display if there is already a VNC server running on that -display. +display. Use the `--display` option to change the display number. The script runs _qemu-kvm_ in the background with _nohup_. So you can log out of the creation host and it will continue running. @@ -164,7 +167,8 @@ attention to how the disk is partitioned. (Desktop Experience)" or "Windows Server 2020 Datacentre (Desktop Experience)". They do not apply to the non-desktop editions (previously called "server core editions") that do not have a - Windows graphical environment. + Windows graphical environment. The non-desktop editions are for + use with remote management tools and/or the command line. 5. Read the licence terms and, if you accept them, check the "I accept the Microsoft Software Licence Terms" checkbox and press the "Next" button. @@ -173,7 +177,7 @@ attention to how the disk is partitioned. not an upgrade. Initially, there won't be any drives to install Windows on, because -the disk drivers for them have not been loaded. +Windows does not come with drivers for the VirtIO virtual disk drives. #### 2d. Use the VirtIO disk drivers @@ -193,7 +197,12 @@ No drives will be available until the VirtIO drivers are loaded. A "Drive 0 Unallocated Space" will be detected. If a small disk image is being used, there may be a message claiming more space - is recommended. + is recommended. This may or may not be a problem, depending on + the purpose of the image. That is, depending on exactly how much + space is available, a successful installation might still be + possible. But it is possible for it to Windows to be installed, + but there will not be enough space to install updates and/or + additional applications. 5. Press "Next" and Wait for the installation to finish. (About 20 minutes.) @@ -201,21 +210,40 @@ No drives will be available until the VirtIO drivers are loaded. 6. Set the administrator password and press the "Finish" button. This administrator password will be reset by either _cloud-init_ - or _sysprep_ (used as a final step when preparing the image). + or _sysprep_ (used as a final step when preparing the image). So + this password is only for temporary use, while the image is being + created, and it can be forgotten after that. #### 2e. VirtIO network drivers +Note: some versions of Windows may strongly suggest that connecting to +the Internet is desirable during the installation process. But it +should be possible to say there is no Internet connection, and to +proceed with the installation without it. The VirtIO network driver +(unlike the VirtIO disk driver) is installed _after_ the Windows +installation process has been fully completed. + Install the VirtIO network drivers to use the virtual network interfaces. -1. Type Ctrl-Alt-Delete into the VNC session to sign in. - The VNC client probably has a special feature to - do this (e.g. the _Command_ > _Ctrl-Alt-Del_ menu item in - the _Screens_ application). +1. Type Ctrl-Alt-Delete into the VNC session to sign in. The VNC + client should have a special feature to do this (e.g. in the macOS + _Screens_ application, use the _Command_ > _Ctrl-Alt-Del_ menu item), + since typing those keys would affect your local computer rather + than the guest system. 2. Open the _Device Manager_, by launching the _Control Panel_ and the selecting _System and Security > Hardware > Device Manager_. + The "Hardware" link is in the navigation list on the left side of + the window. In some versions of Windows, it is called "Hardware + and sound". + + The _Control Panel_ is often hard to find, since Microsoft is + pushing users to their fancy, but limited, _Settings_ application. + It might be available as a tile on the Start menu, or is buried + under the "Windows Systems" folder of the list of all applications. + Under "Other Devices" the Ethernet controller should appear as an "Unknown device" whose driver could not be found. @@ -223,14 +251,20 @@ interfaces. (under the "Other devices" section). By double clicking on it, or right clicking on it and selecting Properties. + In some versions of Windows, it will be called "Ethernet + Controller" instead of "Unknown device". But it should still + have a yellow hazard triangle on its icon. + 4. Press the "Update Driver" button. 5. Choose "Browse my computer for driver software". 6. Press the "Browse..." button. -7. Select the top level of the second CD Drive (E:) (i.e. do not need - to choose a subdirectory) and press the "OK" button. +7. Select the top level of the second CD Drive (E:) (unlike for the + VirtIO disk driver, a specific subdirectory and file does not need + to be chosen for the VirtIO network driver) and press the "OK" + button. 8. Ensure the "Include subfolders" checkbox is checked and press the "Next" button. @@ -240,8 +274,10 @@ interfaces. 9. Press the "Install" button. -10. When prompted to "allow your PC to be discoverable by other PCs and - devices on this network", press the "no" button. +10. When prompted to "allow your PC to be discoverable by other PCs + and devices on this network", press the "no" button. It is also + also possible to press "yes", but it is more secure to choose + "no"---unless that functionality is really needed. 11. Press the "Close" to close the driver update success window. @@ -251,6 +287,8 @@ interfaces. 14. Close the Control Panel Hardware window. +A Windows restart might be required for the network drivers to work. + #### 2f. Time zone When the image is instantiated, it will have a (virtual) hardware @@ -285,7 +323,7 @@ turning off the display to save power and it is more likely to cause confusion when trying to use it. 1. Open the Control Panel Power Options. Launch the Control Panel and select - Hardware > Change power-saving settings. + _Hardware > Change power-saving settings_. 2. Select the radio button for the "High performance" power plan. @@ -303,9 +341,11 @@ Turn on automatic updates and install the current updates. 1. Open the Windows Start Menu. -2. Choose Settings. +2. Choose _Settings_ -- yes, the fancy, but limited, application and + not the _Control Panel. It is the gears icon in the Start menu. -3. Choose Update & Security (the window may need to be scrolled up to see it). +3. Choose _Update & Security_ (the window may need to be scrolled up + to see it). 4. Press the "Check for updates" button, if needed. @@ -323,15 +363,15 @@ Turn on automatic updates and install the current updates. ### Step 3: Optionally install additional software -If additional configuration needs to be performed, restart the guest +If additional configuration needs to be performed, run a guest virtual machine by booting off the disk image. - $ ./q-image-maker.sh --run image.qcow2 + $ ./q-image-maker.sh run image.qcow2 As before, connect to the VNC server (through the ssh tunnel) without using a VNC password. -The `--iso` option can still be used to attach ISO images to install +The `--iso` option can be used to attach ISO images to install software from. ### Step 4: cloud-init and sysprep @@ -388,7 +428,8 @@ enable the out-of-box-experience when Windows is first started. For example, it removes the administrator's password. If _sysprep_ was not run as the last stage of setting up -CloudBase-Init, it will have to be run manually. +CloudBase-Init, or CloudBase-Init is not installed, _sysprep_ will +have to be run manually. 1. Start Windows PowerShell. diff --git a/openstack-images/q-image-maker.sh b/openstack-images/q-image-maker.sh index 5e372bc..d8601de 100755 --- a/openstack-images/q-image-maker.sh +++ b/openstack-images/q-image-maker.sh @@ -27,7 +27,7 @@ #---------------------------------------------------------------- PROGRAM='q-image-maker' -VERSION='2.0.0' +VERSION='2.0.1' EXE=$(basename "$0" .sh) EXE_EXT=$(basename "$0") @@ -163,7 +163,7 @@ Options for upload: -n | --name imageName name of glance image (default: "$DEFAULT_IMAGE_NAME_PREFIX