There are two ways of creating a custom image: static and dynamic. The static way consists of creating an instance, customizing it, and then taking an image from this customized instance. The static way is the easiest task.

Some characteristics of your desired custom image depends on information you have only at the instance creation time; in this case, the information should be dynamically transferred to the instance creation process to create the final customize instance.

This article explains how to parameterize an image, the process at a concept level, and step-by-step instructions on how to perform every sub-task. Once the image is parameterized, the parameters can be sent to the instance creation process using the IBM® Cloud portal or APIs.

This is a very important behavior of the IBM Cloud because it allows you to create a tailored instance on the fly.

In this article, we'll create a new image with VNC-access configured and a user already created. The parameters are:

• The VNC password.
• The user name.
• The user password.

The goal is to be able to request via the IBM Cloud portal the creation of an instance based on the image you parameterized; I'll show you that I was able to provide the parameters and get access to the server via VNC using the specified user/password.

Let's first discuss the concepts behind parameterization and the overall process.

Parameterization concepts

In general, parameters are placeholders for actual values or types that are filled in at a point of use. Parameterization (also, parametrization/parameterisation/parametrisation) is the process of deciding and defining the parameters necessary for a complete or relevant specification

A variant task is one that requires parameters and therefore is best handled with parameterization. Examples from this article include setting up the VNC password or creating the user.

An invariant task is one that doesn't require parameters (like requesting an operating system instance); this one can be done with the easy static way.

Back to top

Parameterization process

The overall process works like this:

1. Determine which tasks are variant or invariant.
2. Create an instance and realize the invariant tasks. This consists of:
   1. Requesting an instance.
   2. Editing the /etc/xinetd.d/vnc file.
   3. Adding the xstartup file.
   4. Setting up the firewall.
3. Save the instance as an image in your private catalog. This consists of:
   1. Saving the instance.
   2. Downloading the corresponding Rational Asset Manager asset.
4. Create the variant attributes.
5. Implement the variant tasks. This consists of:
   1. Adding the VNC password.
   2. Creating the user and setting the password.
6. Call the implemented task.
7. Describe where the implemented tasks should be uploaded.
8. Update Rational Asset Manager with the scripts.
9. Create an instance based on the new custom image.

The IBM Cloud provides a way to parameterize image. The images are stored in Rational® Asset Manager (RAM). By posting files in the Rational Asset Manager asset representing the image, you can interact with the instance creation process.

One of the files is the parameters.xml file. Add XML tags to this file to describe the fields you want to capture during the instance request. An example of a field tag is:

<field name="userID" label="User ID" type="string"/>

You'll find more tag information in the support documentation available via the IBM Cloud portal.

The parameters.xml file is copied in the instance in the /etc/cloud directory and can be read to extract the field value entered during the instance request.

In Rational Asset Manager, you can also post a number of files to upload into the instance at an earlier stage of the instance boot process. A file called scripts.txt is used to describe the file to import from Rational Asset Manager and its final location on the instance. For example:

cloud-startup5.sh=/etc/init.d/cloud-startup5.sh
addvncpassword.txt=/etc/cloud/addvncpassword.sh
createUser.txt=/etc/cloud/createUser.sh
replace.txt=/etc/cloud/replace.pl

The cloud-startup5.sh is used when the instance is started in GUI mode (level init 5); cloud-startup3.sh launched during startup level 3 is text mode. The instances used here are launched in GUI mode meaning that you have to update the cloud-startup5.sh file.

Another file, provided by default on the Linux® images, is a Perl script file used to retrieve the value of a specific tag from an XML file. It is located at /usr/bin/extract-parameters.xml in the instance creation process to extract the parameters set during the instance request.

Now let's look at the instructions to parameterize an image.

Back to top

Step 1. Identify variant or invariant tasks

The tasks to set up the environment include:

1. Request an OS instance.
2. Edit the /etc/xinetd.d/vnc file.
3. Set the VNC password.
4. Add the xstartup file.
5. Set up the firewall.
6. Create the user.
7. Set the password for the user.

Next, determine if the task is a variant or invariant task. If the task requires parameters, then the task is a variant task:

1. Request an OS instance.
   Invariant; the customization will be done based on this OS.
2. Edit the /etc/xinetd.d/vnc file.
   Invariant; the change can be hard coded since none of the parameters are needed to set up this file.
3. Set the VNC password.
   Variant; the password is one of our parameters.
4. Add the xstartup file.
   Invariant; this file doesn't need any of our parameters.
5. Set up the firewall.
   Invariant; the port to access VNC is static.
6. Create the user.
   Variant; the user name is one of our parameters.
7. Set the password for the user.
   Variant; the password is one of our parameters.

Back to top

Step 2. Create an instance and realize the invariant tasks

To create an instance and realize the invariant tasks:

1. Request an instance. Request an instance based on the SuSE 11 operating system, as usual enter a name, a key-pair ... and so on.
2. Edit the /etc/xinetd.d/vnc file. Follow the instructions specified on the IBM Cloud User Guide accessible from the Support tab of the IBM Cloud portal.
3. Add the xstartup file. Follow the instructions specified on the IBM Cloud User Guide accessible from the Support tab of the IBM Cloud portal.
4. Set up the firewall. Follow the instructions specified on the IBM Cloud User Guide accessible from the Support tab of the IBM Cloud portal. (See Figure 1.) As you can see, the IBM Cloud User Guide contains important details for this step.

Back to top

Step 3. Save the instance as an image in your private catalog

Because all of the invariant tasks are executed you can save this image in your private catalog. The parameters to recreate an instance from this image are stored in Rational Asset Manager as an asset. You can download the asset and modify it for your own needs.

The two steps for saving an instance as an image in your private catalog are:

1. Save the instance. You can use the usual method to save your instance as image. Provide a name and a description to this image.
   
   Figure 2. Configure private image
   
   
   
2. Download the corresponding Rational Asset Manager asset that corresponds to your image in the Rational Asset Catalog:
   1. On the Control panel of the IBM Cloud portal, click View Assets Catalog. You are redirected to Rational Asset Manager.
      
      Figure 3. Rational Assets Catalog
      
      
      
   2. Click My Dashboard.
   3. Click on your asset.
      
      Figure 4. My Dashboard
      
      
      
   4. Download the asset and save it in your environment.
      
      Figure 5. Download asset
      
      
      
   5. Select content.
      
      Figure 6. Content list
      
      
      

You'll see a number of files, including the parameters.xml.

Back to top

Step 4. Create the variant attributes

To create the variant attributes:

1. Open the parameters.xml file from your local environment.
2. You will see some firewall rules.
3. Add the field tags in the final parameters.xml file (Listing 1):
   
   Listing 1. The final parameters.xml file
   

   <?xml version="1.0" encoding="UTF-8"?> <parameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation= "platform:/resource/com.ibm.ccl.devcloud.client/schema/parameters.xsd"> <firewall> <rule> <source>0.0.0.0/0</source> <minport>1</minport> <maxport>65535</maxport> </rule> </firewall> <field name="userID" label="User ID" type="string"/> <field name="userPassword" label="User Password" type="password" pattern="^\w*(?=\w*\d)(?=\w*[a-z])(?=\w*[A-Z])\w*$" patternErrorMessage="Invalid Password. Must contain at least 1 number, at least 1 lower case letter, and at least 1 upper case letter."> </field> <field name="vncPassword" label="VNC Password" type="password" pattern="^\w*(?=\w*\d)(?=\w*[a-z])(?=\w*[A-Z])\w*$" patternErrorMessage="Invalid Password. Must contain at least 1 number, at least 1 lower case letter, and at least 1 upper case letter."> </field> </parameters>

   
   
4. Take care: The final file should not contain any carriage return/linefeeds (CR/LF); only LFs are allowed. Use a DOS editor command such as dos2unix to convert the CR/LF to LF. This is valid for ALL files that you would like to upload to the Rational Asset Manager asset.

   Also, don't put any LFs in the middle of a tag.

5. Upload the parameters.xml into the asset, click the pencil to edit the asset. Browse to your new parameters.xml file.
   
   Figure 7. Edit the asset
   
   
   
6. Click Update located at the bottom of the page and provide a comment.
7. Come back on the portal and select your image from your private catalog.
   
   Figure 8. Select your image
   
   
   
8. Click Next located at the bottom of the pop-up window.
9. Provide name as usual and click Next. You should see a new pop-up window containing the different parameters you defined in the parameters.xml file. If not, it is possible that the image specification is cached in your browser. Try removing all the cookies related to the portal (www-147.ibm.com) and try again. This should solve the problem.
   
   Figure 9. Add instance
   
   
   
10. Click Cancel.

Back to top

Step 5. Implement the variant tasks

In short, you need:

• One script to add the VNC password.
• Another script to create a user.

These scripts are called from the cloud-startup5.sh. A final, third script describes where the other scripts are uploaded in the asset.

A habit of mine is to post all custom scripts in the /etc/cloud directory so I can find them easily. All scripts are posted under the activation_scripts directory in the Rational Asset Manager asset.

You can run the scripts in your instance to test them.

Step 5.1. Add the VNC password

Following is the script to add the VNC password; the file addvncpassword.txt is provided.

mkdir /root/.vnc
echo "vncPassword" | vncpasswd -f > /root/.vnc/passwd
chmod 777 /var/lib/gdm

The last line was added due to an issue in the SuSE 11-based image. Not adding this line in the script will create a pop-up error while connecting to the instance using VNC. The first line and the last line of this script could be executed also using the static method instead of being part of this script.

Step 5.2. Create the user and set the password

Following is the script to create the user; the file createUser.txt is provided.

useradd -m userID
echo "userPassword" | passwd --stdin userID

For security purposes, you can set the password as expired to force the user to provide a new password at first login.

Back to top

Step 6. Call the implemented task

The implemented task is called via the cloud-startup5.sh which is launched during init 5 (denoting SuSE OS, multi-user, GUI-based).

Adapt the cloud-startup5.sh as shown in Listing 2:

# Required-Stop:
# Should-Stop:
# Default-Start:     3
# Default-Stop:
# Short-Description: Cloud startup
# Description:       Extract and set user password
### END INIT INFO

case "$1" in
    start)
        echo "== Cloud Starting"
        if [ ! -e /etc/cloud/idcuser_pw_randomized ]; then
            echo "Randomizing idcuser password"
            echo idcuser:`< /dev/urandom tr -dc _A-Z-a-z-0-9 |head -c16` |
              /usr/sbin/chpasswd
            touch /etc/cloud/idcuser_pw_randomized
        fi
        if [ ! -e /etc/cloud/parameters.xml.done ]; then
            echo "VNC Create password"
            perl /etc/cloud/replace.pl /etc/cloud/addvncpassword.sh vncPassword
            . /etc/cloud/addvncpassword.sh
            echo "Create user"
            perl /etc/cloud/replace.pl /etc/cloud/createUser.sh userID
            perl /etc/cloud/replace.pl /etc/cloud/createUser.sh userPassword
            . /etc/cloud/createUser.sh
            cp /etc/cloud/parameters.xml /etc/cloud/parameters.xml.done
        fi
        ;;
    stop)

        echo "== Cloud Stopping"

        ;;
    *)
        echo "Usage: $0 {start|stop}"
        exit 1
        ;;
esac

In the added lines:

        if [ ! -e /etc/cloud/parameters.xml.done ]; then
            echo "VNC Create password"
            perl /etc/cloud/replace.pl /etc/cloud/addvncpassword.sh vncPassword
            . /etc/cloud/addvncpassword.sh
            echo "Create user"
            perl /etc/cloud/replace.pl /etc/cloud/createUser.sh userID
            perl /etc/cloud/replace.pl /etc/cloud/createUser.sh userPassword
            . /etc/cloud/createUser.sh
            cp /etc/cloud/parameters.xml /etc/cloud/parameters.xml.done
        fi

I used the file /etc/cloud/parameters.xml.done as semaphore to run these lines only at the first boot of the server.

I used a Perl script, replace.pl, which replaces a keyword by its corresponding value found in the parameters.xml in a given file. You can use any other means to activate the same result.

The first Perl command replaces the keyword vncPassword in the addvncpassword.sh file using the value described for this keyword in the parameters.xml.

Then call the addvncpassword.sh file. The addvncpassword.txt file is uploaded in /etc/cloud using a mechanism I'll explain later.

The second Perl script replaces the userID keyword; the third Perl script replaces the userPassword keyword in the createUser.sh file with the information found in the parameters.xml.

Then the createUser.sh is called.

Finally the parameters.xml file is copied on the parameters.xml.done to avoid running these lines twice.

For security purposes, you can add some lines to the script to erase the password value from the parameters.xml.

Back to top

Step 7. Describe where the implemented tasks should be uploaded

All of these tasks/scripts should be uploaded at the correct location during the instance creation time. The IBM Cloud provides a mechanism which consists of creating a file (called scripts.txt) that basically describes where each file should be uploaded.

This is the scripts.txt file:

cloud-startup5.sh=/etc/init.d/cloud-startup5.sh
addvncpassword.txt=/etc/cloud/addvncpassword.sh
createUser.txt=/etc/cloud/createUser.sh
replace.txt=/etc/cloud/replace.pl

In this example, the cloud-startup5.sh is uploaded at /etc/init.d/cloud-startup5.sh location and so on.

Back to top

Step 8. Update RAM with the scripts

You already uploaded the parameters.xml, now upload the following scripts under the activation_scripts directory of the asset:

• addvncpassword.txt
• cloud-startup5.sh
• createUser.txt
• replace.txt
• scripts.txt

To upload the scripts:

1. Edit your asset and click More options.
   
   Figure 10. More options
   
   
   
2. Click activation_scripts. If activation_scripts doesn't exist, create it by using the "Create a folder" option.
   
   Figure 11. activation_scripts
   
   
   
3. Click Add (Ajouter) and browse over to your files.
   
   Figure 12. Add files
   
   
   
4. Click Update.
   
   Figure 13. Update
   
   
   
5. Click Update again after you've provided a comment. In this case, add the comment "Upload scripts."
   
   Figure 14. Update comments
   
   
   
6. Now you can test.

Back to top

Step 9. Create an instance based on the new custom image

To create an instance based on the new custom image:

1. Go in your private catalog and select your customized image.
   
   Figure 15. Select image
   
   
   
2. Click Next.
3. Enter the Request Name then click Next.
   
   Figure 16. Configure image
   
   
   
4. Enter the VNC user and passwords.
   
   Figure 17. Configuration additional parameters
   
   
   
5. Click Next then submit the information.
6. Now you can connect using VNCViewer with the new instance IP address.
   
   Figure 18. VNCViewer connection details
   
   
   
7. Notice the :1 after the IP address. Click OK.
8. Type the VNC password and click OK.
   
   Figure 19. VNCViewer authentication
   
   
   
9. Enter "user" and "password" and you'll get Figure 20.
   
   Figure 20. Login window
   
   
   

10. Success!

    
    
    Figure 21. Success!
    
    
    

Back to top

Bonus

You can change the GetStarted.html file to provide more information on your asset. Once you modify this file, upload it via RAM. You'll see GetStarted.html at the bottom of the Control panel of the IBM Cloud portal when you select your new instance.

And that's it.

Resources

Learn

• For more on how to perform tasks in Release 1.2, visit these resources:
  • Tips: Up and download files from a Windows instance.
  • Tips: Install IIS web server on Windows 2008 R2.
  
  
• For more on Release 1.2, listen to the Brian Snitzer podcast.
  
  
• In the developerWorks cloud developer resources, discover and share knowledge and experience of application and services developers building their projects for cloud deployment.
  
  
• The next steps: Find out how to access IBM SmartCloud Enterprise.
  
  

Get products and technologies

• See the product images available on the IBM SmartCloud Enterprise.
  
  

Discuss

• Join a cloud computing group on My developerWorks.
  
  
• Read all the great cloud blogs on My developerWorks.
  
  
• Join the My developerWorks community, a professional network and unified set of community tools for connecting, sharing, and collaborating.
  
  

About the author

In recent years, Dominique Vernier focused on Java technologies and cloud architecture. He also has been working in information technology for quite a while where he earned a broad knowledge in such technologies and products as messaging, database, SOA, EAI, client/server, C/C++, and existing frameworks. Dominique also has extensive knowledge in industry areas such as telecom, CRM, logistics, and insurance. He is the author/co-author of four patents having to do with state engines and resource management. At present, Dominique is in charge of the IBM SmartCloud Enterprise solutions on the IBM GTS Global Team.

Rate this article

Comments

Back to top

Table of contents

• Parameterization concepts
• Parameterization process
• Step 1. Identify variant or invariant tasks
• Step 2. Create an instance and realize the invariant tasks
• Step 3. Save the instance as an image in your private catalog
• Step 4. Create the variant attributes
• Step 5. Implement the variant tasks
• Step 6. Call the implemented task
• Step 7. Describe where the implemented tasks should be uploaded
• Step 8. Update RAM with the scripts
• Step 9. Create an instance based on the new custom image
• Bonus
• Resources
• About the author
• Comments

Next steps from IBM

Learn more, join the cloud community

---

• Community: Cloud computing conversations led by IBM community members
• Buy: Try IBM software on IBM SmartCloud Enterprise

Dig deeper into Cloud computing on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers