![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
Customizing a Windows®-based image on IBM® SmartCloud Enterprise is slightly more complicated than its Linux® counterpart. Despite these complications, customizing a Windows-based image is not only possible but necessary for many business needs. This article describes some tips for automating software, user input settings and configurations on an IBM SmartCloud Enterprise Windows-based image. This article does not cover all issues but addresses many of the common problems and possible solutions to help you avoid image capture failures and unexplainable instance provisioning issues.
This article is intended for individuals and companies who are interested in customizing a Microsoft® Windows-based image using IBM SmartCloud Enterprise. A basic understanding of IBM SmartCloud Enterprise is assumed such as navigating the cloud administrator portal, and basic Windows operating system experience is recommended.
Table 1 shows the differences between customizing a Linux-based image and a Windows-based image. Some of these differences are discussed in further detail throughout the article.
Table 1. Differences between customizing Linux- and Windows-based images
| Customization component | Similarities and differences |
|---|---|
| parameters.xml type=file | Adding an additional parameter of type=file is not currently supported on Windows-based images. |
| extracting parameters.xml values | The same Perl script can be run on both image types; however, Perl does not come pre-installed on Windows-based images. |
| activation scripts | Same structure required. The user customizing the image might have both FirstProvisionStartup.bat and VMInstanceStartup.bat scripts. It is important to note that if a configuration step is needed, it must wait until after Windows has logged a user in (such as an exe or a macro script to automate a set of configuration steps); these scripts most likely are not the solution you are looking for. If one of these scripts includes a call that waits, the instance provisioning step will most likely fail. Alternative solutions are described in this article. |
| start .exe in an activation script | As mentioned, executing user processes through activation scripts is not currently supported since it may lead to provisioning failures. At the time of this article, the support team was looking for ways to include this feature. |
| capturing step | Even though a user can still use the IBM SmartCloud portal to save an image of an existing instance, there are a few additional steps that are required before the capture will complete successfully. | Note: These differences were valid at the time of this publication and since then could have changed. |
There are a number of articles available that describe in detail how to customize IBM SmartCloud Enterprise images, including the comprehensive User's Guide provided on the Support tab of the SmartCloud Enterprise portal (you must be logged in to access). However, despite best attempts to address Windows-specific issues, there remains a need for additional information on why a Windows-based image might perform differently than a Linux-based image.
The three options for having commands run on a Windows-based image are:
The option you choose is entirely up to your environment and system requirements. This article describes some of the issues users might run into when using each option. Keep in mind that a combination of these options can be the best choice for your needs.
Before continuing, a word about custom images. A custom image is created when you save a SmartCloud instance and make configuration changes to that instance, for example using a custom parameters.xml file or activation scripts. An image is considered to be Windows-based if the operating system of the instance from which the image was saved was also using Windows. Whether the new image is intended for private, shared, or public use, this article describes how to configure a Windows-based image.
Extracting parameters.xml values
Similar to the Linux solution, with a Windows-based image it is possible to extract the values a user enters as answers to the additional parameters that are stored in the parameters.xml file on new instances. For a Windows image, this file can be found under the c:/cloud directory. To quickly extract values, a Perl script is available that understands the parameters.xml structure and markup. However, Perl does not come pre-installed on a Windows-based image. To use the same Perl script you must first download and install a version of Perl onto the instance before saving it as an image. See the Resources section for a link to the Perl download website. The extracted-parameters-new.pl script file is available to download from the Download section.
In most situations the parameters.xml values need to
be extracted only one time. If that is the case for your customized image, place the commands to extract the values in the run-once
activation script. Listing 1 is an example of extracting two parameters named param1 and param2 respectively to a text file named extracted.txt.
Listing 1. Command to extract parameters.xml values
@echo off
CD C:/dir/where/perl/script/is/stored
perl extract-parameters-new.pl -v param1 parameters.xml > extracted.txt
echo. >> extracted.txt
perl extract-parameters-new.pl -v param2 parameters.xml >> extracted.txt
start extracted.txt
|
A couple of Windows batch file tips to note here.
The first is the use of the double >>. This tells the script to place the value at the end of the file rather than rewrite the existing content.
Secondly, echo. >> extracted.txt adds a new line to the file,
which allows for easier reading of the resulting text file. To open the newly created
file, use start extracted.txt. Opening the file is
optional. For security reasons, it is recommended that you delete the resulting
file where the extracted values were stored as well as the parameters.xml file after
the configuration and installation steps are complete. Those files may contain user credentials and password information.
Similar to a Linux-based image, a Windows-based image allows the image creator to define a set of activation scripts that are to run once on instance creation and always on instance start. In a Windows-based image, these script files are saved in the c:\cloud directory:
- FirstProvisionStartup.bat: Runs one time. This is a good place to put the commands to extract the parameters.xml.
- VMInstanceStartup.bat: Runs every time the instance is started.
The text files that are used to create these scripts can be named anything as long as they are mapped correctly and in the scripts.txt mapping definitions file. However the name of the script files (FirstProvisionStartup.bat and VMInstanceStartup.bat) are fixed and cannot be changed. A text file that describes the mapping between the script files and the text files is required and must be named scripts.txt. As with the Linux images, Windows images require these script files be saved in the activation_scripts directory in IBM Rational Asset Manager for the image. An example of the content of the scripts.txt mapping is shown in Listing 2.
Listing 2. Scripts.txt command mapping
Run_always_on_VMreboot.txt=C:\cloud\VMInstanceStartup.bat
Run_only_once_on_VMreboot.txt=C:\cloud\FirstProvisionStartup.bat
|
In Listing 2, there are three files in the activation_scripts directory: Run_always_on_VMreboot.txt, Run_only_once_on_VMreboot.txt, and scripts.txt.
If a configuration step is needed that requires the user to be logged in (to ensure that specific Windows services are running such as an exe or a macro script to automate a set of configuration steps), the use of the VMInstanceStartup.bat and FirstProvisionStartup.bat scripts most likely are not the solution you are looking for. If one of these scripts includes a call that waits, the instance provisioning step will likely fail. To verify that the problem with an instance provisioning failure was related to the activation scripts, try any of these options, then create the instance again:
- Delete the activation scripts directory from the image asset catalog in IBM Rational Asset Manager (RAM).
- Comment out the commands in the scripts and update in Rational Asset Manager.
- Clear out the contents of the files and update in Rational Asset Manager.
To edit the activation scripts or any other aspect of an existing image, follow these steps:
- Go to the Control Panel tab in IBM SmartCloud Enterprise portal.
- Click View asset catalog at the top of the Control Panel. IBM Rational Asset Manager opens.
- The landing page that opens in Rational Asset Manager is typically the Assets tab that lists all of the available assets in IBM SmartCloud Enterprise. You can search here for the image.
- If the image is a private image or an image created under your account, click the My Dashboard tab. A more manageable view of the images you have the authority to modify is displayed.
- Find the image to customize and click the pencil icon in the row of the image.
Figure 1. RAM My Dashboard View
- At the bottom of the page, there is an area that lists all of the files that are associated with the image. As mentioned previously, the most efficient way to update the activation scripts is to ZIP the content and upload the ZIP file. To do that, click Browse then find and select the ZIP file on your local machine. Alternatively, click the More options link, which refreshes the page and lets you click on the activation_scripts directory. From there you can delete and replace files individually.
- Once satisfied with the changes, click Update.
- Provide an optional comment about the changes made and click Update.
As mentioned previously, if an exe or a set of macros is required to run after an instance of the custom image is successfully provisioned, the FirstProvisionStartup.bat file isn't necessarily the best choice of location for the commands; it could cause the instance provisioning step to fail. One alternative is to use Windows Registry entries.
There are four Windows Registry keys that can be used to notify Windows to run a command or set of commands after a user logs in:
- HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run
- HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunOnce
- HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run
- HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\RunOnce
Notice there are two key options, Run and RunOnce. RunOnce, like the name implies, is
for those commands that you want to run a single time. By default, the entry is deleted before the command is run. To cause the command to be deleted after the command is run, place an exclamation point in front of the key name. For example, !KeyName.
Because the focus of this article is about creating Windows images, use the LOCAL_MACHINE registry entries rather than the CURRENT_USER entries. Using LOCAL_MACHINE registry entries ensures that any user logging in causes the commands to run; this isn't directly tied to a specific user so any user logged into the instance can cause the commands to run. Use of CURRENT_USER requires special permissions for the user that the entry was created under. Because the Windows administrative account is subject to change with new instance creation, you need to make sure that each of these unknown users have permission to execute the commands. Therefore, use the LOCAL_MACHINE registry entries.
This article is not intended to be a complete guide on Windows scripting or Windows Registry entry manipulation. This section is included as a suggested alternative to using the IBM SmartCloud Enterprise activation scripts. For additional details on Windows Registry keys and writing batch files, see the Resources section.
Figure 2 shows the Windows Registry window.
Figure 2. Windows Registry window
To access the Windows Registry window click Start > and type regedit in the run box. After the Windows Registry window opens, it
is possible to navigate to the appropriate Run or RunOnce key and add new key values.
To add a new value to the Windows Registry, right-click in the key area blank space and select New > String value. Give the new key value a name. Remember to use the exclamation point if you want to use the feature described earlier. A new key is created.
To modify the value, right-click on the key and select Modify. A new window opens. Enter a command, a location, a program, or batch file to run. Figure 2 shows an example of a new key that points to a batch file that finishes the automation and configuration steps for the custom image when a new user logs into the instance.
Another way to cause a Run command to run a single time is to include a delete command registry entry after the other commands have completed. Listing 3 is an example of how to write a Windows batch command line to delete a registry entry.
Listing 3. Batch file command to delete a Windows Registry entry
REG DELETE HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
/v REGKEYNAME /f |
Listing 4 shows a Windows batch file command that queries the Windows Registry to see if a registry key exists.
Listing 4. Batch file command to query Windows Registry entries
REG QUERY HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
/v REGKEYNAME || start SOMECOFIGEXE.exe |
If the key exists then nothing happens, if it doesn't exist, then the command following the double pipe (||) is run. The key is used as a semaphore. This is one way to get custom macros or an executable file to run a single time rather than using the FirstProvisionStartup.bat file.
Once the executable file is run, a command can be executed to add a registry entry so that the next time the instance is started the .exe file is not run because the query command finds the registry entry. To add a registry entry, use the REG ADD command shown in Listing 5.
Listing 5. Batch file command to add a Windows Registry entry
REG ADD HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
/v REGKEYNAME /f |
With all of these batch command examples the location of the registry entry key (for example, LOCAL_MACHINE vs. CURRENT_USER) might need to be updated to match the location where the registry entry is saved.
When software is installed on a Windows-based image, the software might have an associated Windows service. Carefully verify that the user associated with these services is a generic user rather than the specific user that was used to create the Windows-based instance. Otherwise, when the instance is saved as an image and a new instance is created, unless the Windows account is the same, users might notice some odd behavior from the installed software because the new Windows user account doesn't have the correct permissions to start and stop the software.
Figure 3. Windows services
To modify a Windows service so any user can start and stop the service:
- Click Start.
- Click Administrative Tools.
- Select Services. The Windows services window opens as shown in Figure 3.
- Find the service that is incorrectly associated with a specific Windows User Account. If you are not sure about the name of the service, scroll through the list focusing on the Log On As column. If the value is something other than Local System or Network Service, it is likely associated with a specific user account.
- Double-click the name of the service.
- A new window opens. Click the Log On tab (Figure 4).
Figure 4. Windows services Log On window
- The radio button for This account is selected. Click the button for Local System account.
- Click OK.
Now when the instance is saved as an image and later provisioned as one or more new instances, Windows services will not be reliant on a specific Windows user account.
Creating a private Windows image
When it comes to capturing an image, Windows images are a little more complicated than Linux-based images. Although the final step of selecting an instance in the IBM SmartCloud Enterprise portal and clicking create private image is the same, if this step is run before a set of additional steps, the capture will fail. This section provides a basic overview and breakdown of the required configuration steps. The Resources section provides a link to a document that describes these configuration steps in detail.
Note: There are additional steps that must be followed before capturing a Windows-based image. If they are not followed correctly, the creation of the Windows image can fail. Check the User's Guide for the most current steps.
To configure Windows:
- Login to the instance using Remote Desktop Protocol.
- Manually reboot the instance.
- Login again. Make sure you disable popup windows that prevent Windows from starting up smoothly. Examples might include firewall warnings, windows updates, etc. To verify all popups were successfully disabled, restart the instance.
- Synchronize the System Time:
- Right-click the Windows Taskbar.
- Select Properties.
- Select the Notification Area tab.
- Check Clock.
- Click OK.
- Right-click the time that is now displayed in the Windows Taskbar.
- Click Adjust Date/Time.
- Select the Internet Time tab.
- Click Change Settings.
- Click Update now. The time will synchronize. If it doesn't work the first time, try again.
If these steps aren't working for your Windows-based image, look online for the correct steps to synchronize the date and time.
- Activate Windows:
- Click Start.
- Right-click the Command Prompt icon.
- Click Run as administrator.
- Type
slmgr -ato. Press Enter. - Click OK on the message window.
- Double-click the desktop icon to run AUTOLOG.bat.
- Manually shut down the instance: Start > Log off > Shut down.
- The instance will shutdown and you can create a private image using the IBM SmartCloud Enterprise portal.
See the Resources section for a link to capturing a Windows image document.
This article described many of the differences between a Linux-based image and a Windows-based image in the IBM SmartCloud Enterprise environment. Additionally, it provided a number of workaround solutions to known issues with Windows images that are intended to ease the customization and capturing efforts of an IBM SmartCloud Enterprise Windows image.
| Description | Name | Size | Download method |
|---|---|---|---|
| Perl script to extract parameters.xml values | extracted-parameters-new.pl | 3KB | HTTP |
Information about download methods
Learn
- Try
IBM SmartCloud Enterprise
or learn more to decide whether it is right for your business.
- Read this article, Get started with the IBM SmartCloud Enterprise, for basic information about IBM SmartCloud Enterprise.
- Ready to capture a Windows-based image?
Read this PDF detailing required
preparation steps for successful capture of a Windows image (You need to login with your developerWorks ID first.)
- Read the
IBM
SmartCloud Enterprise User's guide available on the Support tab after you login to the SmartCloud
Enterprise portal.
- Read this reference document to learn more about
Windows Registry entries.
- There are numerous resources available
online for writing batch files; How To
Write A Simple Batch (.bat) File gets you started.
-
For more on how to perform tasks in the IBM Cloud, visit these resources:
- Upload and download files from a Windows instance.
- Install IIS web server on Windows 2008 R2.
- Create an IBM Cloud instance with the Linux command line.
- Create an IBM Cloud instance with the Windows command line.
- Extend your corporate network with the IBM Cloud.
- High availability apps in the IBM Cloud.
- Parameterize cloud images for custom instances on the fly.
- Windows-targeted approaches to IBM Cloud provisioning.
- Deploy products using rapid deployment service.
- Integrate your authentication policy using a proxy.
- Configure the Linux Logical Volume Manager.
- Deploy a complex topology using a deployment utility tool.
- Provision and configure an instance that spans a public and private VLAN.
- Secure IBM Cloud access for Android devices.
- Recover data in IBM SmartCloud Enterprise.
- Secure virtual machine instances in the cloud.
-
In the developerWorks cloud developer resources, discover and share knowledge and experience of application and services developers building their projects for cloud deployment.
- Find out how to access IBM SmartCloud Enterprise.
Get products and technologies
-
Download Perl to execute perl scripts, such as the parameters.xml extraction perl script, on Windows-based images.
-
See the product images available for IBM SmartCloud Enterprise.
Discuss
- Ask questions and get answers on your Windows customization question using the IBM SmartCloud Enterprise Support Community.
The primary focus of this group is to provide technical support to ensure you are able to access and provision images on IBM SmartCloud Enterprise.
-
Join a cloud computing group on developerWorks.
-
Read all the great cloud blogs on developerWorks.
-
Join the developerWorks community, a professional network and unified set of community tools for connecting, sharing, and collaborating.
Lisa Seacat DeLuca is an Advisory Software Engineer for the Advanced Cloud Technologies team under IBM's Global Technology Services, GTS. Lisa has over six years of Enterprise Software Development experience and led the OAuth support effort for the IBM SmartCloud offering. She holds a Masters of Science in Technology Commercialization from the University of Texas and a Bachelors of Science in Computer Science from Carnegie Mellon University.
Table of contents
Next steps from IBM
Learn more, join the cloud community
