developer's guide to building vapps and virtual appliances pdf

Developer’s Guide to Building vAppsand Virtual Appliances

VMware Studio 2.6

This document supports the version of each product listed andsupports all subsequent versions until the document is replacedby a new edition. To check for more recent editions of thisdocument, see http://www.vmware.com/support/pubs.

EN-000831-00

http://www.vmware.com/support/pubs

VMware, Inc.3401 Hillview Ave.Palo Alto, CA 94304www.vmware.com

2 VMware, Inc.

Developer’s Guide to Building vApps and Virtual Appliances

You can find the most up-to-date technical documentation on the VMware Web site at:

http://www.vmware.com/support/

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to:

[email protected]

Copyright © 2008–2012 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents.

VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

http://www.vmware.com/support/

http://www.vmware.com/support

mailto:[email protected]

http://www.vmware.com/go/patents

http://www.vmware.com/go/patents

VMware, Inc. 3

Contents

About This Book 9

Getting Started with VMware Studio

1 Introduction to VMware Studio 13Overview 13

What Is a vApp? 13

What Is a Virtual Appliance? 14

Audience for VMware Studio 14

Key Features 15

Architecture of VMware Studio 16

Virtual Appliance Management Infrastructure (VAMI) 17

Build System 17

VMware Studio Plugin for Eclipse 18

Integration with VMware vCenter Update Manager 18

Roadmap of This Manual 18

Linux and Eclipse Developers 18

Windows Developers 19

Developers Planning to Build vApps 19

Automating Builds from the Command Line 19

ISVs Shipping Virtual Appliances 19

2 Deploying and Using VMware Studio 21Prerequisites 21

Deploying VMware Studio 22

Deployment Options 22

Supported Distribution Formats 23

Deployment Procedure 23

Security of Self‐Signed SSL Certificate 24

Modifying the Network and Time Zone Settings 24

Setting the Time Zone 25

Using VMware Studio Web Console 25

Accessing the VMware Studio Web Console 25

Shutting Down the VMware Studio Appliance 25

Setting Time Zone in the Web Console 25

Network Configuration in the Web Console 25

Updating the VMware Studio Appliance 26

Automatic Updates 26

Update Repository 27

3 Building VMs and vApps with VMware Studio 29Outline of VM Build Procedure 29

Outline of vApp Build Procedure 29

Acquiring the Operating System ISO 30

Requirements for Building 64‐Bit VMs 30

Output Formats 30


4 VMware, Inc.

Supported Products to Run Generated VMs and vApps 30

VMware vSphere User Privileges for Provisioning 31

ESX/ESXi and vCenter Server User Privileges 31

ESX/ESXi and VirtualCenter User Privileges 32

User Privileges for Provisioning with vCloud Director 32

Developing a Linux‐Based VM

4 Creating a Linux‐Based VM 35Overview 35

Prerequisites – OS and Application 35

Accessing the Web Console 35

Operating System ISO Image 36

Application Director Templates 37

Appliances with Application Stack 37

Just Enough Operating System (JeOS) 37

Footprint Reduction 37

ISO of Qualifying Custom Linux OS 37

Adding Support for a New Linux OS 37

Requirements 38

Support Files for the New OS 38

Fedora 11 As an Example 39

Application Packages 39

Adding On Demand Repositories 40

Creating an On Demand Repository 40

Specifying Packages in Build Profiles 40

Creating a VM Build Profile 40

Web Console Tab Reference 42

Description Tab 42

Hardware Tab 43

OS Tab 44

Application Tab 46

Management Tab 46

Output Tab 48

Build Settings Tab 50

Building a VM from the Build Profile 52

Testing the Generated VM 52

Reiterating the Build Process 53

VMware Tools Installed in a Generated VM 53

Migrating Build Profiles from Studio 1.0 or 2.0 53

5 Packaging a Linux Application 55VMware Studio Make Package (mkpkg) Tool 55

Options of the Make Package Tool 55

Example of Creating a DEB Package 56

Example of Creating an RPM Package 57

Operating System Native Tools 58

DEB Native Packaging 58

RPM Native Packaging 58

TAR Archive as Input Format 59

Operating System Footprint Reduction 60

Just Enough Operating System 60

VMware, Inc. 5

Contents

6 Adding a Linux Management Service 61VMware Studio VAMI Service 61

Default Management Services 62

Creating a Management Service 63

service.xml 63

view.xml 64

Creating a Vanilla VM 64

Underlying CLI 64

Importing a Management Service 64

Customizing the Initialization Script 65

7 Managing a Linux Update Repository 67Overview of Updates 67

Generating an Update 68

Updates on CDROM 69

Updates Requiring Reboot 70

Digitally Signing an Update 70

Adding Your EULA to an Update 70

Publishing an Update 71

Publishing an Update Repository from ZIP 71

Testing Against a Staging Update Repository 72

Diagnosing Failed Updates 73

Update Repository XML 73

Supporting Central Updates with VMware vCenter Update Manager 74

8 Using the VMware Studio Plugin for Eclipse 75Requirements of VMware Studio Plugin for Eclipse 75

Getting Started with VMware Studio Plugin for Eclipse 75

Packaging Applications to Run In a Virtual Machine 76

Creating Management Services 77

Additional Eclipse Features 77

Uninstalling the Eclipse Plugin 78

Developing a Windows‐Based VM

9 Creating a Windows‐Based VM 81Overview 81

Prerequisites – OS and Application 81

Accessing the Web Console 81

Operating System ISO Image 82

OS Image Installation Options for Windows 82

Virtual Disk Size for Windows Server 82

Adding Support for a New Windows OS 83

Windows Application Packages 83

Creating a VM Build Profile 83

Additional Fields for Windows Reference 84

OS Tab 84

Application Tab 86

Building a VM from the Build Profile 87

Testing the Generated VM 87

Reiterating the Build Process 88

Provisioning a Windows ISO in vSphere Datastore 88


6 VMware, Inc.

10 Packaging a Windows Application 89About VMware Studio Package for Windows 89

Repository of Windows Application Packages 89

Creating a Windows Application Package 90

Registered Exit Codes 91

Environment Variables when installing Packages 91

Developing a vApp for vSphere

11 Creating a vApp from VM Builds 95Introduction to Building a vApp 95

Prerequisites 95

Creating a vApp Build Profile 95

Web Console Tab Reference 96

Description Tab 97

VMs Tab 97

Start Order Tab 98

Resources Tab 98

Output Tab 98

Building a vApp Build Profile 99

Inspecting the vApp Build 100

Deleting a vApp Build 100

Testing the Generated vApp 100

Importing vApp Profiles 100

12 Guidelines for Creating Virtual Appliances 101Outline of Virtual Appliance Build Procedure 101

VMware Recommendations 101

Choosing OVF Version 101

Choosing Virtual Hardware Version 102

User Accounts 102

Include Update Agent 102

Footprint Reduction 102

Partitioning Disk for System and User Data 102

VMware Ready Virtual Appliances 102

Guidelines for Adding Kernel Extensions 102

13 Building from the Command Line 103Using the Command Line 103

Retrieve OVF Properties 105

14 Build From an Existing VM 107Importing an Existing VM Using the CLI 107

Prerequisites 107

How It Works 108

Discovering an Existing VM 108

Two‐Step Existing VM Discovery 108

Modifying the Import Profile 109

Building with the Import Profile 109

Existing VM Capabilities and Limitations 109

VMware, Inc. 7

Contents

Appendixes

A Management Services Web API 113Root Object 113

VAMI Container 113

vami.container.navigate 113

vami.container.logout 113

vami.container.newHistoryItem 114

vami.container.isLogin 114

vami.container.getUser 114

vami.container.getSessionID 114

VAMI Container Callbacks 114

vami.container.registerOnShowCallback 114

vami.container.registerOnHideCallback 115

vami.container.registerOnNavigateCallback 115

VAMI I/O 115

vami.io.httpGet 115

vami.io.httpPost 116

VAMI Log 116

vami.log.info 116

vami.log.warn 116

vami.log.error 117

Managing Builds 117

Discovery Reports 117

Old Builds 117

B IPv6 Networks and Virtual Appliances 119Supporting IPv6 in Virtual Appliances 119

IPv6 in Virtual Appliances 119

Changing the IPv6 Configuration 119

About IPv6 Support 120

DHCPv6 Availability 120

IP Configurations 120

About SLAAC 120

Name Service 121

Subnetworks and Routing 121

Avoiding Potential DNS Conflicts 121

Automatic Name Service 121

Conclusion 121

C Security with SSH and SSL 123Installing SSH on Windows Workstation 123

Checking Veracity of an SSL Certificate or SSH Key 124

D Editing XML Build Profiles 127Introduction 127

Structure of VM XML Build Profiles 127

Useful Attributes Not Displayed in the VMware Studio Web Console 136

Customizing the Footer in the Web Console 137

Creating Virtual Disks, Partitions, and Virtual Devices 137

Logical Volume Management in Build Profile 139

Signing OVF Files 139

Unmounting CDROM or ISO After a Build 140


8 VMware, Inc.

Resource Allocation Setting Data 140

Structure of vApp XML Build Profiles 141

E Troubleshooting 145Resolving VMware Studio Issues 145

Resolving Eclipse Plugin Issues 149

Glossary 151

Index 155

VMware, Inc. 9

VMware® Studio is an integrated development tool that takes existing software applications, packages them

into virtual machines and vApps, and builds virtual appliances ready to run on VMware platform products.

This book, the Developer’s Guide to Building vApps and Virtual Appliances, provides information about creating

virtual machines and vApps using VMware Studio 2.6.

Revision HistoryThis book is revised with each release of the product or when necessary. A revised version can contain minor

or major changes. Table 1 summarizes the significant changes in each version of this book.

VMware provides several different SDK products, each of which targets different developer communities and

target platforms. To view documentation for the various SDK products, and the current version of this guide,

go to http://www.vmware.com/support/pubs/sdk_pubs.html.

VMware Studio ForumIf you have questions about VMware Studio or want to interact with other users and developers, go to the

community forum at http://communities.vmware.com/community/vmtn/vam/studio?view=discussions.

For news about OVF and vApp development, go to the VMware blog at http://blogs.vmware.com/vapp/.

Intended AudienceThis document is intended for developers, independent software vendors (ISV), system integrators (SI), value

added resellers (VAR), hardware appliance vendors (HAV), IT professionals, and datacenter administrators

who want to create quick‐starting virtual machines, vApps and virtual appliances with VMware Studio. For

information about deploying vApps and virtual appliances created by VMware Studio, see the companion

manual, User’s Guide to Deploying vApps and Virtual Appliances.

About This Book

Table 1. Revision History

Revision Description

2012‐03‐02 Revision for the VMware Studio 2.6 “Faraday” release.

2011‐04‐15 Major revision for the VMware Studio 2.5 “Edison” release.

2010‐11‐04 Internal version for the VMware Studio 2.1.1 update.

2010‐07‐13 Major revision for the VMware Studio 2.1 release.

2009‐08‐28 Final version for the VMware Studio 2.0 release.

2009‐06‐29 Retitled Developer’s Guide to Building vApps and Virtual Appliances for Studio 2.0 Beta.

2009‐02‐05 Corrections made to the first version, but no new material.

2008‐09‐05 First version of the Guide to Building and Implementing Virtual Appliances for VMware Studio 1.0.

http://www.vmware.com/support/pubs/sdk_pubs.html


10 VMware, Inc.

VMware Technical Publications GlossaryVMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions

of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.

Document FeedbackVMware welcomes your suggestions for improving our documentation. Send your feedback to

[email protected].

Technical Support and Education ResourcesThe following sections describe the technical support resources available to you. To access the current versions

of other VMware books, go to http://www.vmware.com/support/pubs.

Online and Telephone Support

To use online support to submit technical support requests, view your product and contract information, and

register your products, go to http://www.vmware.com/support.

Support Offerings

To find out how VMware support offerings can help meet your business needs, go to

http://www.vmware.com/support/services.

VMware Professional Services

VMware Education Services courses offer extensive hands‐on labs, case study examples, and course materials

designed to be used as on‐the‐job reference tools. Courses are available onsite, in the classroom, and live

online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides

offerings to help you assess, plan, build, and manage your virtual environment. To access information about

education classes, certification programs, and consulting services, go to http://www.vmware.com/services.


mailto:[email protected]


http://www.vmware.com/support

http://www.vmware.com/support/services

http://www.vmware.com/services/

VMware, Inc. 11

Getting Started with VMware Studio


12 VMware, Inc.

VMware, Inc. 13

1

This chapter includes the following topics:

“Overview” on page 13

“Architecture of VMware Studio” on page 16

“Roadmap of This Manual” on page 18

OverviewVMware Studio is an integrated development tool that takes existing software applications and packages them

into virtual machines and vApps that are ready to run and optimized for VMware product platforms.

VMware Studio can build both Linux‐based VMs and Windows‐based virtual machines and vApps, running

single tier or multitier applications.

Linux‐based virtual machines that VMware Studio generates contain an in‐guest management agent with a

Web console that an ISV can brand and ship as part of a customized virtual appliance. VMware Studio serves

as an extension to the ISV’s build system, generating automated builds of virtual machines and vApps

containing the latest software binaries. Virtual machines and vApps generated by VMware Studio are in an

industry‐standard format, enabling them to run on many virtualization platforms.

What Is a vApp?

VMware recently introduced the vApp, a software solution optimized for cloud computing. A logical entity

composed of one or more virtual machines, the vApp can be moved and managed as a unit. A vApp specifies

and encapsulates components of a multitier application as well as the operational policies and service levels

associated with it. The vApp gives application owners a standard way to describe policies for an application,

which different datacenters can consistently interpret and run. The vApp is a category of virtual applications

that can be built by ISVs, system integrators, value‐added resellers, and onsite IT administrators.

The Open Virtualization Format (OVF) standard 1.0 is employed to represent a single virtual machine or

combination of multiple virtual machines. As implemented, draft OVF standard 0.9 cannot represent more

than one virtual machine. You can deploy a vApp through vCenter Server with the vSphere Client, or with

ovftool. VirtualCenter 2.5 and ESX/ESXi 3.5 supported OVF 0.9 only. You can run all or part of a vApp on ESX/ESXi 3.5 if you deploy the vApp through vCenter Server 4.

See http://www.vmware.com/appliances/learn/ovf.html for details about the OVF standard (DMTF DSP0243).

From a management perspective, a vApp acts like a virtual machine object. It has power operations, networks,

datastores, and its resource use can be configured. See the OVF and vApp chapters of vSphere Virtual Machine

Administration Guide for vApp management information.

From an implementation perspective, a vApp container is a specialized resource pool that is extended with

compute resources, product information, and importability. In the VMware vSphere API Reference, VirtualApp (the managed object type for vApp) contains virtual machines.

Introduction to VMware Studio 1

http://www.vmware.com/appliances/learn/ovf.html


14 VMware, Inc.

What Is a Virtual Appliance?

Virtual appliances are prebuilt software solutions, comprising one or more virtual machines and applications,

which are packaged, updated, maintained, and managed as a unit. Unlike traditional hardware appliances,

software appliances let customers easily acquire and deploy preintegrated solution stacks.

Virtual appliances are usually built on a standard operating system (OS) and run as a virtual machine (VM).

With virtual appliances, ISVs can create a single application stack, reducing the cost and complexity of

deployment and management. It is possible to ship preinstalled, preconfigured solutions that allow customers

to plug solutions into their computing environments. For customers, deploying and managing software is

easier when the applications are delivered in a virtual appliance. The following items summarize the benefits

of virtual appliances:

Accelerate time to market – Customers can quickly download and power‐on your virtual appliance.

Reduce distribution overhead – The same virtual appliance runs on most VMware product platforms.

Increase reliability – VMware Studio builds an optional update repository for automatic patching.

Enhance security – Appliances are less vulnerable to security breaches than a general‐purpose OS.

Lower support costs – Virtual appliances require little configuration and no maintenance.

Audience for VMware Studio

If you are a software developer at an ISV, VMware Studio can assist you in delivering your applications as

virtual appliances, quickly and effectively. If you are an information‐technology professional or system

administrator, VMware Studio can help you package existing operating systems and applications for your

virtualized datacenter for use within the enterprise. VMware Studio can build both Linux‐based VMs and

Windows‐based virtual machines and vApps, running single tier or multitier applications.

Figure 1‐1 illustrates the workflow to create, distribute, and update a virtual appliance. A software vendor

packages the software for distribution to corporate customers and end‐users, who deploy the package on a

virtualization platform. VMware Studio can optionally build an update repository, and embed the URL of the

update repository into the virtual appliance, which periodically checks for updates after deployment.

Figure 1-1. VMware Studio Workflow

Within the enterprise, these two boxes might be joined together. Within the same organization, IT developers

use VMware Studio to package virtual appliances for delivery to datacenter customers. Administrators control

operational policies and service levels after deployment and configuration.

VMware, Inc. 15

Chapter 1 Introduction to VMware Studio

Key Features

VMware Studio is useful for ISVs building single or multitier appliances and for developers who want to

create a standardized user or development environment by packaging specific application stack components

and tools into a virtual machine or vApp.

Build virtual appliances.

If you have an existing application or you are building a new application, VMware Studio can help you

virtualize it. Follow the best practices and guidelines set by VMware to create production‐ready virtual

appliances for new markets and to reduce the scope of hardware platform testing.

Build vApps.

Packaging multiple virtual machines as multitier applications can be made more convenient with the help

of VMware Studio to create a vApp container. You can define the startup and shutdown order, enabling

two‐click deployment and power‐on of the vApp. You can define resource limits and properties that are

visible to all the virtual machines contained in a vApp. For example, a virtual machine containing the

application server can know the IP address of a virtual machine containing its database server.

VMware vFabric Application Director profiles.

VMware Studio 2.6 contains build profiles for VMware vFabric Application Director appliances based on

CentOS, RHEL, SLES, and Ubuntu. VMware vFabric Application Director is an easy way to package

software for the cloud. See http://www.vmware.com/go/application‐director for details.

Extend the in‐guest management framework.

The initial release of VMware Studio embedded an in‐guest management framework into Linux‐based

VMs, and provided a network proxy and an update service as part of this framework. In subsequent

releases, the management framework and Web console interface became extensible, and later optional.

You can add a custom management service when building a virtual appliance, as required by your

application. If a custom service has an associated Web interface, you can make the interface visible in the

Web console, which can contain a link to the application that you package in the virtual appliance.

Automatically resolve package dependencies.

VMware Studio builds a VM starting from a relatively minimal OS footprint. VMware Studio can inspect

application packages and, if they specify the correct set of OS package dependencies, install the packages

into the VM build. Additionally if these OS packages have dependencies on other OS packages, Studio

ensures that all required packages get installed, provided they are available in the ISO image of the OS.

Package complex applications for virtual environments.

Complex multitier applications can span virtual machines, just as they can span physical machines.

Components can run on different operating systems, communicating over the network. VMware Studio

helps you package multitier applications into a vApp that runs efficiently under VMware vSphere.

Support for a wide range of VMware provisioning engines.

VMware Studio can use different VMware platform products to generate builds of virtual appliances.

Supported platform products include vCenter Server, ESX/ESXi hosts, and VMware Workstation.

VMware Studio Plugin for Eclipse IDE.

The Eclipse IDE provides many tools to assist with application development. The VMware Studio Plugin

for Eclipse can help with the iterative process of coding and testing, especially for developers comfortable

with Eclipse. With the plugin, developers can code using Eclipse, and quickly switch into the Web console

to build the resulting virtual appliance or vApp.

Existing Linux VM as input.

VMware Studio allows developers to avoid building a virtual machine from scratch each time. After you

build a virtual machine with VMware Studio, or obtain a qualifying Linux virtual machine from

elsewhere, it can serve as input for a subsequent build (CLI only). This can save time when you are

changing only the software version, or only the application mix, of a virtual appliance.


16 VMware, Inc.

Support for IPv6 and multiple NICs

VMware Studio can now build VMs and appliances with multiple network interface cards. Users are

allowed to configure the NICs and set Static or DHCP IP values, and support both IPv4 and IPv6.

Support for vCloud Director 1.0

As of VMware Studio 2.5, you can build virtual appliances using vCloud Director 1.0. You can then deploy

the resulting OVF with vCloud Director. OVF support for vCloud is not identical to vSphere. For instance,

single VM OVFs that enable IP pools, causing some OVF property declarations to contain vmw:qualifier attributes, do not deploy in vCloud, and vCloud Director 1.0 does not support custom OVF properties.

Retrieve OVF properties from CD or DVD

You can tailor a virtual appliance using custom OVF properties. VMware Studio 2.5 and later support the

OVF transport=iso flag. When the user deploys a VM on vSphere, answering client prompts for

property values, vCenter Server constructs an ISO image containing these property key/value pairs and

makes the ISO image available on the appliance’s CDROM drive.

Support for Studio Interchange Format

A SIF package is an archive for the items necessary to build an appliance, like a recipe for dependent parts.

Items include the build profile, the application packages, scripts, and other files. A SIF file can be imported

into another VMware Studio installation, allowing the second installation to re‐create the appliance. You

can choose not to include certain item types (for instance, the operating system ISO image) in the package.

You can use SIF to share appliance build profiles and dependencies for Windows as well, allowing the

building blocks of a Windows appliance without violating Microsoft redistribution license policies.

Patch Updates for VAMI and VMware Studio

Periodic updates for VMware Studio are available in an update repository as patches. VMware Studio

now enables updates for itself, so you can download bug fixes when available from an update repository.

Architecture of VMware StudioAs shown in Figure 1‐2, VMware Studio offers a choice of interfaces for the developer, including Web browser,

Eclipse plugin, and command‐line interface.

Figure 1-2. VAMI Components

VMware, Inc. 17


The VMware Studio Web console is a browser‐based interface that simplifies the creation and building of

virtual appliances. VMware recommends that you start with this interface. VMware Studio also includes a

build service and VAMI, the virtual appliance management infrastructure.

An Eclipse plugin is provided so you can use the same Eclipse integrated development environment (IDE) for

developing your application as for packaging it in a virtual machine. A command‐line interface assists you

with automation. For example, you can schedule periodic builds using the CLI rather than the Web console.

Virtual Appliance Management Infrastructure (VAMI)

VAMI is the runtime management component that VMware Studio installs in a Linux‐based virtual appliance.

VAMI is based on the common information model (CIM) with SFCB being the CIM server and lighttpd being the Web server. VMware Studio offers these VAMI components, all optional:

Welcome screen and the virtual machine console – To display welcome messages, set the time zone, and

log in to configure networking (the CLI screen in Figure 1‐2 shows a login session).

First boot EULA prompt on the virtual machines console – Requests acceptance of the end‐user license

agreement (EULA).

Management services including CIM and VAMI – See “VMware Studio VAMI Service” on page 61.

Management Web console – Web console interface to VAMI services (as in Browser screen of Figure 1‐2).

Appliance boot scripts – To be executed during first or subsequent boots of the virtual machine.

VMware Tools for the OS – VMware Tools improve operations of the guest operating system running in

a virtual machine. For details see “VMware Tools Installed in a Generated VM” on page 53.

You can customize a virtual appliance by adding tabs to the user interface. See “VMware Studio VAMI

Service” on page 61 for details about custom service tabs in a Linux virtual appliance.

You can also build a “vanilla” virtual machine containing no VMware Studio runtime components at all, or a

virtual machine with some combination of selected components. See “Creating a Vanilla VM” on page 64.

Build System

To create a VM or a vApp, you formulate a build profile using the VMware Studio Web console or Eclipse

interface. The build profile specifies the ISO image of a Linux or Windows operating system and the software

applications to run on that operating system. For a Linux‐based VM, the build profile also specifies in‐guest

services, in other words VAMI. The left side of Figure 1‐3 shows inputs to the build system.

Before you build a VM or vApp, VMware Studio validates the build profile. To provision a VM, the build

system uses a VMware product platform to create a virtual machine from the operating system ISO and the

application set you specify. A successful VM build is exported to a network‐accessible location on the VMware

Studio appliance. This VM contains the OS and application packages as defined in build profile. The VM also

has boot scripts configured, the in‐guest management framework embedded, and is customized according to

specifications of your build profile.

On VMware product platforms that support the vSphere API (formerly the VIM API), the build system uses

the ovftool to create and transport the VM. On VMware product platforms that do not support the vSphere

API, the build system uses the VIX API to create and transport the VM.

To create a vApp, the build system takes a set of VM build profiles or successfully built VMs, and packages

them together with an OVF descriptor. As the developer of a vApp, you can specify start order and resource

allocation for the constituent VMs and applications, but many aspects of the vApp remain flexible until the

administrator decides at deployment time.


18 VMware, Inc.

Figure 1-3. VMware Studio Architecture

VMware Studio Plugin for Eclipse

VMware Studio provides an optional plugin for Eclipse that can be used with the Eclipse IDE. The plugin

serves as a bridge between the Eclipse IDE and VMware Studio to create VMs and vApps that include software

binaries that you compile in the Eclipse environment. To get started using the Eclipse interface, see Chapter 8,

“Using the VMware Studio Plugin for Eclipse,” on page 75.

Integration with VMware vCenter Update Manager

VMware vCenter Update Manager integrates with VMware Studio’s update service to enable centralized

management of virtual appliance updates. Update Manager 3.5 and later provide default virtual‐appliance

upgrade baselines to scan and upgrade a virtual appliance to the latest released or critical‐update version.

Update Manager also lets you create virtual‐appliance upgrade baselines. Please note that vApps cannot be

updated as one unit. In the Update Manager 4.0 documentation, vApps are treated as container objects of

virtual machines or virtual appliances.

For information about Update Manager 4.0, see http://www.vmware.com/support/pubs/vum_pubs.html.

Roadmap of This ManualTo deploy and configure VMware Studio, read Chapter 2, “Deploying and Using VMware Studio,” on page 21.

To get an overview of the inputs to and results of the build system and the build process in general, read

Chapter 3, “Building VMs and vApps with VMware Studio,” on page 29.

Linux and Eclipse Developers

Linux developers can continue with Chapter 4, “Creating a Linux‐Based VM,” on page 35. To create Linux

packages for inclusion in this Linux‐based VM, see Chapter 5, “Packaging a Linux Application,” on page 55.

Developers who want to create custom management services for inclusion in the appliance Web console of the

Linux‐based VM can read Chapter 6, “Adding a Linux Management Service,” on page 61.

Developers familiar with the Eclipse IDE can use the VMware Studio Plugin for Eclipse to easily package

applications in the form of virtual appliances. Development, testing, and packaging can be done with the

Eclipse IDE. To learn more, see Chapter 8, “Using the VMware Studio Plugin for Eclipse,” on page 75.

http://www.vmware.com/support/pubs/vum_pubs.html

VMware, Inc. 19


Windows Developers

Windows developers can continue instead with Chapter 9, “Creating a Windows‐Based VM,” on page 81.

To create Windows application packages for inclusion in this Windows‐based VM, see Chapter 10, “Packaging

a Windows Application,” on page 89.

Developers Planning to Build vApps

Developers planning to build multiple‐VM vApps should in addition read Chapter 11, “Creating a vApp from

VM Builds,” on page 95.

Automating Builds from the Command Line

Developers and ISVs wanting to generate nightly builds of virtual machines, vApps, and virtual appliances

with their latest application software binaries should read Chapter 13, “Building from the Command Line,”

on page 103.

ISVs Shipping Virtual Appliances

ISVs planning to build virtual appliances should read, in addition to other relevant chapters, Chapter 12,

“Guidelines for Creating Virtual Appliances,” on page 101. When shipping virtual appliances, ISVs might

plan on establishing an update repository to remotely publish patches for virtual appliances deployed in

customer environments. To create the update repository and learn details about the update process, read

Chapter 7, “Managing a Linux Update Repository,” on page 67.


20 VMware, Inc.

VMware, Inc. 21

2

This chapter describes how to deploy and configure VMware Studio, and contains the following topics:

“Prerequisites” on page 21

“Deploying VMware Studio” on page 22

“Modifying the Network and Time Zone Settings” on page 24

“Using VMware Studio Web Console” on page 25

PrerequisitesTo run VMware Studio and provision virtual appliances, the following components are required:

You can download the VMware Studio software package from the VMware Web site, in your choice of

formats: OVF 0.9, OVF 1.0, OVA, or ZIP. It is best to use ZIP for hosted products like VMware Workstation,

and OVF or OVA for vSphere. Optionally, if you are using Eclipse, you can download the VMware Studio

Plugin for Eclipse. See http://www.vmware.com/support/developer/studio for the download location.

VMware Studio supports one of these virtualization product platforms for building (provisioning) VMs.

The provisioning platform that you use to create a VM must be capable of running the finished VM.

VMware ESX/ESXi 5.0, 4.1, 4.0, or 3.5 through VMware vCenter Server 5.0, 4.1, or 4.0

VMware ESX/ESXi 3.5 through VMware VirtualCenter 2.5

VMware ESXi 5.0

VMware ESX/ESXi 4.1, 4.0, or 3.5

VMware Workstation 7.1, 7.0.1, or 6.5.2

VMware Cloud Director 1.0

Prerequisites if you are provisioning with VMware Workstation:

An SSH daemon (SSHD) must be enabled on the host of VMware Workstation. If Workstation is

hosted on a Windows system, see “Installing SSH on Windows Workstation” on page 123.

If your VMware Workstation is running on a Windows host, start the SSHD service (on the Windows

host) with the option Allow service to interact with desktop.

Ports 7 and 22 must be open. Port 7 is used primarily to validate the update repository server.

The Workstation user interface must be running, and you must designate the user who is currently

logged in to the Workstation host as the provisioning user for VMware Studio.

Ports 7 and 22 must be open. Port 7 is used primarily to validate the update repository server.

Approximately 32GB of available storage space where you deploy VMware Studio.

Deploying and Using VMware Studio 2

http://www.vmware.com/support/developer/studio


22 VMware, Inc.

The following ports on the VMware Studio appliance are used to access the Web console and build VMs:

22 ssh tcp

80 http tcp

5480 https tcp

5488 http 5489 https tcp (for internal communication between lighttpd and SFCB)

VMware Studio requires the following ports to be open on the host running the provisioning product:

7 echo tcp, 22 ssh tcp (for VMware Workstation). On most Linux hosts port 22 is open by default, but

port 7 is not, but you can edit /etc/sysconfig/iptables to open port 7. On Windows you can add

a firewall exception for echo on port 7 and ssh on port 22.

443 https tcp (for VMware ESX/ESXi and VirtualCenter or vCenter Server)

902 vix tcp

Supported browsers are (see the Release Notes for specific version numbers):

Internet Explorer

Mozilla Firefox

Google Chrome

Deploying VMware StudioHow you deploy VMware Studio depends on the provisioning platform you use.

Deployment Options

For simplicity of configuration, you can deploy VMware Studio on the same virtualization product platform

that you plan to use for building VMs. You can also deploy VMware Studio on a different virtualization

platform than the one used for building VMs. For example, if you are running VMware Studio on 32‐bit

hardware, but you are building a 64‐bit virtual machine, you can set the provisioning platform to a remote

64‐bit system. As another example, the remote system might be lightly loaded and capable of faster builds.

Figure 2‐1 illustrates the simplest setup of VMware Studio. The virtualization platform could be almost any

recent VMware platform product. For desktop products, one requirement is an SSH server on the platform’s

host to allow SSH and SCP operations by VMware Studio. For server products, one requirement is a user with

adequate permissions for provisioning. See “VMware vSphere User Privileges for Provisioning” on page 31.

Figure 2-1. Single Host Setup of VMware Studio

Figure 2‐2 illustrates a dual‐host setup of VMware Studio. The virtualization platforms for hosts A and B could

be any of those permitted for a single host, and the virtualization platform does not have to be the same.

The requirements for provisioning through host B are the same as for a single host, except both hosts must be

network connected so VMware Studio on host A can readily access the virtualization platform on host B.

VMware, Inc. 23

Chapter 2 Deploying and Using VMware Studio

Figure 2-2. Dual Host Setup of VMware Studio

Supported Distribution Formats

Selecting a format depends on the virtualization product that you plan to use. VMware Studio is available in

the following formats:

OVF – A descriptor that references VMDK‐format virtual disk files

OVA – Archive containing OVF 1.0 descriptor and VMDK files

ZIP – Archive containing VMX and VMDK files

To deploy VMware Studio on:

VMware vSphere 4 – Use the vSphere Client to import VMware_Studio-<version>_OVF10.ova, or VMware_Studio-<version>_OVF10.ovf and its related VMware_Studio-<version>.vmdk file.

VMware Infrastructure 3 – Use the VI Client to import VMware_Studio-<version>_OVF09.ovf and its related VMware_Studio-<version>.vmdk file.

VMware Workstation – Unzip VMware_Studio-<version>.zip and then use VMware Workstation to

open the extracted VMX file.

vCloud Director 1.0 ‐ Use the Web interface to upload VMware_Studio-<version>_OVF10.ovf (and its associated VMware_Studio-<version>.vmdk file) to vCloud Director as a vApp template in the catalog,

then instantiate the Studio vApp template into a running VM in the desired cloud.

NOTE Both OVF 0.9 and OVF 1.0 of the VMware Studio appliance reference the same VMDK file.

Deployment Procedure

The procedure for deploying VMware Studio is different for the OVF or OVA package than for the ZIP file.

To deploy VMware Studio from OVF or OVA

1 The OVF or OVA format of VMware Studio can be deployed directly from the VMware download Web

server. Alternatively the VMware Studio OVA, or OVF and its associated VMDK file, can be downloaded

to a local Web server or Windows machine where the VMware vSphere or VMware Infrastructure Client

can access it for deploying the appliance. If you decide to download the OVF format of VMware Studio

appliance to a local machine, place the OVF and its associated VMDK file in the same directory.

2 For VMware vSphere 4, run the VMware vSphere Client and click File > Deploy OVF Template. For

earlier releases, run the VMware Infrastructure Client and click File > Virtual Appliance > Import. In

either case, a wizard guides you through deployment.

With vSphere 4, Deploy OVF Template gives you the option of thin provisioning the VMware Studio

virtual machine, which makes it much smaller than otherwise. Disk usage will grow as needed during

building and provisioning of a virtual appliance.

3 Power on the VMware Studio virtual machine.

4 View and accept the EULA.


24 VMware, Inc.

5 When Studio prompts you to specify a new password for the root account, type a password. Retype and

confirm the password at the second prompt. VMware Studio requires the root (superuser) account to

build virtual machines.

The VMware Studio welcome screen appears. By default VMware Studio tries to acquire an IP address

from a DHCP server. To configure static IP, see “Network Configuration in the Web Console” on page 25.

6 Write down the IP address that appears there, Interfaces to VMware Studio: [Web] http://<IP.address>,

because you need this URL to access the VMware Studio Web console. The given http URL redirects to https port 5480.

7 Set a network proxy, change the time zone, or configure a static IP address. For details, see “Modifying

the Network and Time Zone Settings” on page 24.

To deploy VMware Studio from ZIP

1 Download VMware_Studio-<version>.zip to the host of VMware Workstation, and extract the ZIP file

to a directory, for example C:\MyVirtualMachines\VMware_Studio-2.* on a Windows host or

/var/lib/vmware/VirtualMachines/VMware_Studio-2.* on a Linux host.

2 In VMware Workstation, select menu File > Open.

3 Click Browse, navigate to the directory where you extracted the VMware Studio virtual machine, select

VMware_Studio-<version>.vmx and click Open.

4 Power on the VMware Studio virtual machine.

5 Continue with Step 4 of the OVF or OVA deployment.

You are now ready to begin developing with VMware Studio.

Security of Self-Signed SSL Certificate

The VMware Studio appliance is delivered with a self‐signed SSL certificate. If you are developing on a trusted

network, you can choose accept the certificate without verification.

To verify the authenticity of the network connections you are making when developing with VMware Studio,

see “Checking Veracity of an SSL Certificate or SSH Key” on page 124.

Modifying the Network and Time Zone SettingsAfter deploying the VMware Studio appliance you should configure several options. You can use a VMware

console window for this, as described in the following sections. To reach the VMware console window, use the

vSphere Client (formerly the VI Client), or the VMware Workstation application.

The VMware Studio welcome screen on the command console shows the following menu selections at the

bottom of a blue and gray page:

LoginSet Timezone (Current: UTC)

VMware Studio is configured to get networking settings from a DHCP server. If DHCP service is not available

on your network, you might have to configure network parameters yourself.

To manually configure network parameters

1 On the command console below the welcome message, select Login and press Enter.

2 Log in using the root account and the password that you set during deployment in Step 5.

3 Run the following command at the shell prompt:

/opt/vmware/share/vami/vami_config_net

A menu with six or more choices appears. Start with IP Address Allocation for a network interface.

4 If you need help with settings, refer to the User’s Guide to Deploying vApps and Virtual Appliances.

VMware, Inc. 25


Setting the Time Zone

If you want to change time zone for the VMware Studio appliance (not necessary), take the following steps.

To set the time zone

1 From the virtual appliance welcome screen, select Set Timezone and press Enter.

2 In the Please identify a location screen, select your continent or ocean and press Enter.

3 In the country screen, select your region or country and press Enter.

4 In the time zone screen, select an area or time zone and press Enter.

These steps may vary on different virtual appliances. The time zone is set and the welcome screen appears.

Using VMware Studio Web ConsoleThis section outlines procedures to change network settings, shut down, and reboot the VMware Studio

appliance from the Web console. These procedures also work generally for Linux‐based virtual machines that

VMware Studio created, because VAMI provides the tabs described here.

Accessing the VMware Studio Web Console

The Web console is the best way to begin using VMware Studio.

To access the VMware Studio Web console

1 In the section “Deploying VMware Studio” on page 22, the URL to access the VMware Studio Web console

is displayed in Step 6 of the process. With one of the supported Web browsers, go to that location.

2 Type root as the User name. Type the password that you specified in Step 5 of the process “Deploying

VMware Studio” on page 22. Press Enter or click Login.

Shutting Down the VMware Studio Appliance

Click the System tab in the Web console.

On the Information page you see the virtual appliance vendor, appliance name, appliance version, computer

host name, operating system name, operating system version, and OVF environment (if any).

The Reboot and Shutdown buttons are under the Actions heading on the right side of the window.

To stop the virtual appliance, click the Shutdown button.

To restart the virtual appliance, click the Reboot button.

Setting Time Zone in the Web Console

If you want to change time zone (not necessary), click the System tab in the Web console.

On the Time Zone page is a drop‐down menu to select among time zones of the world. Change the time zone

if you did not already do so on the Server Console. Click the Save Settings button to make a change. If you do

not explicitly set the time zone, the default is UTC, Coordinated Universal Time.

Network Configuration in the Web Console

Click the Network tab in the Web console. This tab offers pages for the following operations:

Status – Shows network information for multiple network interface cards, such as the host name,

gateways, DNS servers, network interface name, whether DHCP was used for IPv4, the IPv4 address, the

netmask, whether stateless address auto‐configuration (SLAAC) is set for IPv6, and additional IPv6

information (if any). IPv6 information includes IPv6 address type, IPv4 address with prefix, and auto

address with prefix. After making any changes, click the Refresh button under the Actions heading (on

the right) to obtain current status.


26 VMware, Inc.

Address – Helps you specify IP network information and enable DHCP services and SLAAC. If you

change any network address settings, click Save Settings (on the right) to effectuate your changes. Click

Cancel Changes to discard any changes. You can configure DHCP and SLAAC from this interface, or

from the Server Console.

When the IPv4 address type is set to DHCP, the virtual appliance gets its network settings from your

DHCPv4 server. If you set the IPv4 address type to Static, you must enter values in the following fields:

IPv4 Default Gateway – IPv4 address of the gateway (network router).

Hostname – Host name of the virtual appliance.

Preferred DNS Server – IPv4 address of the primary DNS server.

Alternate DNS Server – IPv4 address of the secondary DNS server.

IPv4 Address – IPv4 address of the virtual appliance.

Netmask – Network mask for the virtual appliance.

If the IPv6 address type is set to SLAAC, the virtual appliance will be assigned an automatic IPv6 address

when the connected network is configured to provide SLAAC addresses. If you set the IPv6 address type

to Static, you must also enter values in the following fields:

IPv6 Address – IPv6 address of the virtual appliance.

Prefix – IPv6 prefix, which specifies address length.

Gateway – Optional IPv6 address of the gateway (network router).

If IPv6 address is Static, the IPv4 address usually is also, in which case the Hostname and DNS Server

fields are required (see above). If you configure a static IPv6 or DHCPv6 address, the virtual appliance

also displays an IPv6 address.

Proxy – Allows you to specify a proxy server and port for accessing external networks (for example, the

wide‐area Internet). Click Save Settings to accept changes that you make to the proxy settings. Click

Cancel Changes to discard changes. You can configure a network proxy from this interface, or from the

Server Console. If you click the check box next to Use a Proxy Server, you must enter a Proxy Server and

Proxy Port; the User name and Proxy Password is optional.

HTTP Proxy Server – Host name or IP address for the proxy server.

Proxy Port – Proxy server communications port.

Proxy User name – A valid user name, if the proxy server requires authentication.

Proxy Password – The valid password, if the proxy server requires authentication.

Updating the VMware Studio Appliance

VMware Studio 2.5 and later can be dynamically updated in the field (these updates provide important bug

fixes done to the VMware Studio 2.5 release), so an Update tab appears in the Web console. The Update tab

has two subtabs:

Status – Lists information about the vendor, appliance name, version, available updates (if any), last check

for updates, and last install time (if done). Also provides buttons to check for updates and install updates.

Settings – Shows the setting of policies for periodically checking and installing Studio appliance updates.

If you are behind a firewall, you might need to set a proxy (see above) to reach the external Web.

Automatic Updates

You can select one of the following update policies:

No automatic updates – The appliance does not check for and install updates. This is the default.

Automatic check for updates – The virtual appliance checks for updates at the scheduled time. If an

update is available, it appears on the Update Status page.

VMware, Inc. 27


Automatic check and install updates – The virtual appliance checks for updates at the scheduled time,

and if one is available, installs it.

If you select either Automatic check for updates or Automatic check and install updates, you can configure

the scheduling. By default, the check occurs daily at 03:00 local time, as determined by your time zone setting.

Update Repository

By default, Studio updates from the VMware vapp‐updates Web site. You can choose instead to update from

a CDROM, or from an alternate update repository URL. This is something you might need to change if you

are inside a restricted local area network. When you change the update repository location:

After you select Use CDROM Updates, insert the update CDROM into a drive that the virtual appliance

can read. The update agent scans the CD drives to find the first update CDROM.

If you select Use Specified Repository, type the URL of the update repository that the Studio appliance

should check. If the URL requires authentication, provide a valid user name and password.

To make a change, click Save Settings. If you leave Use Default Repository selected, the update agent checks

the vapp‐updates.vmware.com Web site, so set the proxy server and port if required.


28 VMware, Inc.

VMware, Inc. 29

3

This chapter provides an overview of building VMs and vApps with VMware Studio, and contains the

following topics:

“Outline of VM Build Procedure” on page 29

“Outline of vApp Build Procedure” on page 29

“Acquiring the Operating System ISO” on page 30

“Output Formats” on page 30

“Supported Products to Run Generated VMs and vApps” on page 30

Outline of VM Build ProcedureYou begin building a virtual machine by creating a build profile that defines a container for the base OS

configuration and the included software packages.

To build a VM with VMware Studio

1 Define a build profile with the features you want. You select an operating system for the VM, virtual

hardware, and application packages to include. For Linux‐based VMs, you can also configure the

welcome screen, first boot script, and subsequent boot scripts.

2 Build the VM. VMware Studio relies on a VMware virtualization product platform to assemble the

necessary files to build (provision) your virtual machine.

3 Deploy your VM to the appropriate systems and test.

After a Linux‐based VM is deployed, users can manage it from the management Web console, installed in the

virtual appliance as part of VAMI, or from VMware vCenter. Users can also check for and install updates with

the management Web console, if the developer enabled update service and populates the update repository.

Administrators can centrally manage multiple virtual appliances with VMware vCenter.

Outline of vApp Build ProcedureYou begin building a vApp by creating a build profile that defines a container and its constituent VMs.

To build a vApp with VMware Studio

1 Define a build profile containing one or more VMs. You can mix both Linux‐based and Windows‐based

VMs in a vApp. You can specify the power‐on order of the VMs, the CPU and memory resources and

reservations allocated for each, IP assignment policy, OVF properties, and distribution format.

2 Build the vApp. It is required for the VMs in a vApp to be packaged in OVF 1.0 or OVA output format.

3 Deploy your vApp to the appropriate supported systems and test.

Building VMs and vApps with VMware Studio 3


30 VMware, Inc.

Acquiring the Operating System ISOVMware recommends that you download the OS ISO image to the local disk of the VMware Studio appliance,

in /opt/vmware/www/ISV/ISO. For example, you can download the Ubuntu 8.04.4 release by running the

following commands on the VMware console or ssh command line:

cd /opt/vmware/www/ISV/ISOwget http://cdimage.ubuntu.com/releases/8.04.4/release/ubuntu-8.04.4-dvd-i386.iso

If NFS is available on your local area network, a good alternative is to remote mount a network partition where

you have downloaded a collection of ISO images suitable for building VMs, as in the following command run

from the VMware Studio appliance command line:

mount nfs-server.example.com:/vol0/images/iso /opt/vmware/www/ISV/ISO

In Studio 2.1 and later, you can start with any qualifying Linux OS distribution, or with an existing VM. See

“ISO of Qualifying Custom Linux OS” on page 37, or Chapter 14, “Build From an Existing VM,” on page 107.

Requirements for Building 64-Bit VMs

The resource requirements of a guest operating system cannot exceed the hardware capacity of the host

system. If you create a virtual machine from a 64‐bit operating system image, it cannot run on 32‐bit hardware.

See the Knowledge Base article 1003945 Hardware and Firmware Requirements for 64‐Bit Guest Operating Systems

at http://kb.vmware.com for detailed information about 64‐bit virtual machines.

Output FormatsWhen you are finished testing and packaging, you can make the VM and vApp builds accessible to customers.

You can provide a VM or vApp in one or more distribution formats:

OVF 1.0 files can describe a VM and deploy on ESX/ESXi 4.x, or they can describe a vApp and deploy only

through vCenter Server 4 and later, or on vCloud Director 1.0.

OVA files are OVF 1.0 archives for easier distribution, and deploy in the same manner as above. However,

OVA files cannot be deployed on vCloud Director.

OVF 0.9 files deploy on VMware Workstation for Windows, ESX/ESXi 3.5, and through VirtualCenter 2.5

and later.

After extraction, ZIP files create VMX and VMDK files that deploy on VMware Workstation or Player.

Supported Products to Run Generated VMs and vAppsVMs and vApps generated by VMware Studio can run on following VMware product platforms:

VMware vCenter Server VMware vCenter Server 4 and later support both OVF 0.9 and 1.0, VM and vApp,

with virtual hardware versions 4 or 7.

VMware VirtualCenter 2.5 VMware VirtualCenter 2.5 supports OVF 0.9, VM only, with virtual hardware

version 4.

VMware ESX/ESXi 4.x VMware ESX/ESXi 4.x hosts support both OVF 0.9 and 1.0, VM only (vApps when

deployed through vCenter Server) with virtual hardware versions 4 or 7.

VMware ESX/ESXi 3.5 VMware ESX/ESXi 3.5 supports OVF 0.9, VM only (vApps when deployed through

vCenter Server) with virtual hardware version 4.

VMware Workstation VMware Workstation for Windows supports OVF 0.9, VM only, with virtual hardware

versions 4 or 7. With Workstation 7.1 you can separately invoke the bundled ovftool to convert an OVF 1.0 file into the hosted VMX format for Workstation to open.

VMware Player 2.5 and 3.x VMware Player 2.5 and 3.x support a VM with virtual hardware versions 4 and 7.

http://kb.vmware.com/kb/1003945

VMware, Inc. 31

Chapter 3 Building VMs and vApps with VMware Studio

VMware vSphere User Privileges for Provisioning

For provisioning on ESX/ESXi hosts or through vCenter Server, you could create a provisioning user with

fewer privileges than the root login or the Administrator role. You must have Administrator permission to

complete the following procedures.

To assign a provisioning role to a user in vCenter Server

1 Create a new user on the system where the vCenter Server is running.

2 Start the vSphere Client and connect to the vCenter Server.

3 Right‐click the vCenter object (in the Hosts and Clusters tree view) and select Add Permission.

4 In the Assign Permissions dialog, add the new user you created in Step 1 to the Users and Groups list, and

select the new role created (for example vmstudio) as its Assigned Role.

To create a less-privileged user role in vCenter Server

1 Start the vSphere Client and connect to the vCenter Server.

2 Click Administration > Role > Add.

3 Give a name (for example vmstudio) to the new role and assign to it the required privileges.

To assign a provisioning role to a user in ESX/ESXi

1 Create a new user on the ESX/ESXi host. You can do this with the vSphere Client. Connect to the host,

navigate to the User & Groups tab, right click Add, and type the required information into the dialog box.

2 Right click the ESX/ESXi host object (in the Inventory tree view) and select Add Permission.

3 In the Assign Permissions dialog, add the new user you created in Step 1 to the Users and Groups list, and

select the new role created (for example vmstudio) as its Assigned Role.

Obviously these steps do not apply if you are content to provision with a user who has the vCenter Server

Administrator role, or ESX/ESXi root permission.

To create a less-privileged user role in ESX/ESXi

1 Start the vSphere Client and connect to the ESX/ESXi host.

2 Click Home > Roles > Add Role.

Give a name (for example vmstudio) to the new role and assign to it the required privileges.

ESX/ESXi and vCenter Server User Privileges

Here are the user privileges necessary for VMware Studio to provision a VM or vApp on vCenter Server or on

ESX/ESXi 4.0 (vSphere 4):

Datastore

Allocate space

Browse datastore

Low level file operations

Host – Local operations

Create virtual appliance

Delete virtual appliance

Reconfigure virtual appliance

Host profile – View

Network – Assign network


32 VMware, Inc.

Resource

Assign vApp to resource pool

Assign virtual machine to resource pool

Migrate

Query VMotion

vApp – Full permissions

Virtual machine – Full permissions

Set these permissions on the target provisioning platform, not on the VMware Studio host. For example, if

VMware Studio runs on ESX/ESXi 3.5 but provisions on ESX/ESXi 4.0, set user privileges for vSphere 4 on the

provisioning ESX/ESXi 4.0 host.

ESX/ESXi and VirtualCenter User Privileges

Here are the user privileges necessary for VMware Studio to provision a VM on VirtualCenter server or on

ESX/ESXi 3.5 (VMware Infrastructure 3):

Datastore

Browse datastore

File management

Host – Local operations

Create virtual machine

Delete virtual machine

Resource

Assign virtual machine to resource pool

Migrate

Query VMotion

Virtual machine – Full permissions

User Privileges for Provisioning with vCloud Director

For provisioning on vCloud Director, you need to be a user who has the organization administrator role for a

given organization. For example, if you want to use organization buildOrg for provisioning, you must log in

as a user who has the buildOrg organization administrator role.

VMware, Inc. 33

Developing a Linux-Based VM


34 VMware, Inc.

VMware, Inc. 35

4

This chapter describes how to create a Linux‐based virtual machine using the VMware Studio Web console.

Early sections outline the procedures for creating a VM, middle sections cover the build profile configuration

fields, and later sections document advanced topics.


“Operating System ISO Image” on page 36

“Adding Support for a New Linux OS” on page 37

“Application Packages” on page 39

“Adding On Demand Repositories” on page 40

“Creating a VM Build Profile” on page 40

“Web Console Tab Reference” on page 42

“Building a VM from the Build Profile” on page 52

“Testing the Generated VM” on page 52

“Migrating Build Profiles from Studio 1.0 or 2.0” on page 53

OverviewVMware Studio supports the creation of virtual machines containing a Linux‐based operating system,

user‐provided applications, and optionally the Virtual Appliance Management Infrastructure (VAMI) agent.

It also allows customization of the VAMI‐based Web interface if you are shipping the virtual machine as a

virtual appliance and want to rebrand the Web console for your virtual appliance.

Prerequisites – OS and Application

This chapter assumes that you have downloaded the VMware Studio software onto a supported virtualization

product platform, as described in “Deploying VMware Studio” on page 22. You also need:

An ISO image from the list of Linux distributions in “Operating System ISO Image” on page 36.

(Recommended) Your software application packaged for a given Linux distribution, as outlined in

“Application Packages” on page 39.

To work with the current version of Studio, older VM profiles must be updated using the Studio Web console

(Import Profile), or with the studiocli --convertprofile command in the CLI. Profiles within SIF archives

are not automatically converted when imported; you must convert them explicitly.

Accessing the Web Console

To access the Web console with your browser, navigate to the IP address of the VMware Studio appliance.

The access URL appears at install time, as described in “Deploying VMware Studio” on page 22.

Creating a Linux-Based VM 4


36 VMware, Inc.

Operating System ISO ImageTable 4‐1 lists the template profiles for Linux distributions that VMware Studio supports. Specific distributions

and versions are required to ensure compatibility with the VAMI agent.

When possible, Table 4‐1 provides URLs to help you find ISO images, and MD5 checksums to ensure validity.

Linux download locations change frequently, so you might need to use a search engine to find your ISO.

Table 4-1. Template Profiles and Linux Distributions

Template Profile Arch ISO Image Name MD5 Checksum

Application Director 32‐bit CentOS‐5.6‐i386‐bin‐DVD.iso 181142a5845586579d5d4d96e43a4827

64‐bit CentOS‐5.6‐x86_64‐bin‐DVD‐1of2.iso dba0100572e962d08dd88f9482705117

Application Director 32‐bit rhel‐server‐6.1‐i386‐dvd.iso f8c8a310e34d26339c99d462e3557324

64‐bit rhel‐server‐6.1‐x86_64‐dvd.iso a051dbf28ef444a019dc6660efe3e3a4

Application Director 32‐bit SLES‐11‐SP1‐DVD‐i586‐GM‐DVD1.iso 0dd6886858d93501c38854552b9b1b0d

64‐bit SLES‐11‐SP1‐DVD‐x86_64‐GM‐DVD1.iso d2e10420f3689faa49a004b60fb396b7

Application Director 32‐bit ubuntu‐10.04.1‐server‐i386.iso 01f72c846845e4e19aec8a45912e5dda

64‐bit ubuntu‐10.04.1‐server‐amd64.iso 142aaaa77e7da94ae62d7ee2f39d8b3b

http://centos.org

CentOS 5.5 32‐bit CentOS‐5.5‐i386‐bin‐DVD.iso 75c92246479df172de41b14c9b966344

64‐bit CentOS‐5.5‐x86_64‐bin‐DVD‐1of2.iso ac177a5476e3b255b89b659e5b10ba03

JeOS CentOS 5.5 32‐bit CentOS‐5.5‐i386‐bin‐DVD.iso 75c92246479df172de41b14c9b966344

64‐bit CentOS‐5.5‐x86_64‐bin‐DVD‐1of2.iso ac177a5476e3b255b89b659e5b10ba03

http://www.redhat.com

JeOS RHEL 5.5 32‐bit rhel‐server‐5.5‐i386‐dvd.iso 148858b157f275d9153797efddfc83c3

64‐bit rhel‐server‐5.5‐x86_64‐dvd.iso f3119f883257ef9041234feda2f1cad0

RHEL 5.5 32‐bit rhel‐server‐5.5‐i386‐dvd.iso 148858b157f275d9153797efddfc83c3

64‐bit rhel‐server‐5.5‐x86_64‐dvd.iso f3119f883257ef9041234feda2f1cad0

RHEL 6.0 32‐bit rhel‐server‐6.0‐i386‐dvd.iso 291d234c93442405972689b4b41c14bc

64‐bit rhel‐server‐6.0‐x86_64‐dvd.iso f7141396c6a19399d63e8c195354317d

http://download.novell.com

SLES 10.2 32‐bit SLES‐10‐SP2‐DVD‐i386‐GM‐DVD1.iso 2b91efeb8a62e2824302bf9269080252

64‐bit SLES‐10‐SP2‐DVD‐x86_64‐GM‐DVD1.iso dab2c4b8fc9939b33535ab2d321f3f2e

SLES 11.1 32‐bit SLES‐11‐SP1‐DVD‐i586‐GM‐DVD1.iso 0dd6886858d93501c38854552b9b1b0d

64‐bit SLES‐11‐SP1‐DVD‐x86_64‐GM‐DVD1.iso d2e10420f3689faa49a004b60fb396b7

http://cdimage.ubuntu.com/releases/

Ubuntu 8.04.4 32‐bit ubuntu‐8.04.4‐server‐i386.iso ef478e539e991dfa09c3b5b7c589aba6

64‐bit ubuntu‐8.04.4‐server‐amd64.iso 89fdc8289630fceb036c9818ac19ca4c

Ubuntu 10.04.1 32‐bit ubuntu‐10.04.4‐server‐i386.iso 01f72c846845e4e19aec8a45912e5dda

64‐bit ubuntu‐10.04.1‐server‐amd64.iso 142aaaa77e7da94ae62d7ee2f39d8b3b

Sample virtual appliances with built‐in applications

z_Sample with Firefox 32‐bit CentOS‐5.5‐i386‐bin‐DVD.iso CentOS with Firefox browser

z_Sample with LAMP 64‐bit SLES‐11‐SP1‐DVD‐x86_64‐GM‐DVD1.iso SLES with Apache, MySQL, Python

z_Sample with Tomcat 64‐bit ubuntu‐10.04.1‐server‐amd64.iso Ubuntu with Tomcat 6 servlet

http://centos.org

http://www.redhat.com

http://download.novell.com/

http://cdimage.ubuntu.com/releases/

VMware, Inc. 37

Chapter 4 Creating a Linux-Based VM

Application Director Templates

VMware Studio provides prepackaged templates for vFabric Application Director. These are Linux templates

based on CentOS, RHEL, SLES, or Ubuntu. The profiles are preconfigured to produce an OVF that can be

consumed (or used) by vFabric Application Director as a template.

VMware vFabric Application Director is a cloud‐enabled application provisioning solution. Starting with an

intuitive drag‐and‐drop canvas, application architects can visually create deployment topologies that can be

saved and later deployed onto vCloud, with fine‐grained control over installation dependencies, configuration

changes, and editable scripts. See http://www.vmware.com/go/application‐director for details.

VMware recommends that you read the Application Director template considerations in the Web console UI

before modifying any defaults and building a template. These considerations appear on the right under FAQ

on almost every tab when you create or edit a profile.

Appliances with Application Stack

The z_Sample templates build virtual appliances containing open‐source applications. One builds a Linux VM

that launches Firefox after it powers up. Another builds a virtual appliance with pre‐existing LAMP stack

(Linux, Apache, MySQL, and Python). The third builds a virtual appliance with Tomcat application server.

Just Enough Operating System (JeOS)

Templates for a JeOS produce a minimalist image of CentOS or RHEL. They use the same ISO image as their

corresponding OS, but install fewer packages from the distribution media. A JeOS VM does not require a

provisioning server because is built in‐place, in a single file, and then turned into a VMDK.

Footprint Reduction

You can reduce the size of most operating systems by running the VMware Studio footprint reduction scripts.

See “Operating System Footprint Reduction” on page 60 for details.

ISO of Qualifying Custom Linux OS

You can add do‐it‐yourself guest OS support with the --newos option of studiocli, and by editing the XSL descriptions and installation scripts. For more information, see “Retrieve OVF Properties” on page 105 and

Appendix D, “Editing XML Build Profiles,” on page 127.

This allows you to build an XML profile for any qualifying custom Linux OS and especially Linux distributions

that VMware Studio does not officially support.

Adding Support for a New Linux OSTo create a virtual appliance from an OS that VMware Studio does not officially support, use the --newos option to generate a profile. Then import the generated profile and continue with the usual build procedure.

studiocli --newos --osdesc <osdesc> --profile <baseprofile>

For example to add support for RHEL 5.6 32‐bit, run the following studiocli command to create the required

supporting files based on an existing template build profile, RHEL 5.5 32‐bit in this case, because it is the OS

closest to the desired new OS.

studiocli --newos --osdesc "RHEL 5.6" --profile /opt/vmware/etc/build/templates/redhat/5/5/build_profile

A message appears pointing to the location of a TODO_new_os file with instructions about follow‐up tasks to

add new OS support. Afterwards, if you go to the Web console and click the Create Profile button, “RHEL

5.6“appears as one of the available templates for creating a virtual appliance profile.


38 VMware, Inc.

Requirements

VMware Studio currently supports only RPM‐based and DEB‐based operating systems. These systems can use

an unattended installer that may be invoked remotely through the network, such as Anaconda for CentOS and

RHEL, Autoyast for SLES, or Preseed for Ubuntu.

Support Files for the New OS

Table 4‐2 shows the files that are created to support a new guest operating system. At minimum in the profile,

you must update the ISO path, MD5 checksum, vendor, major version, and minor version.

Here are some important fields to verify or update in build_profile.xml:

<Section xsi:type="vadk:JEOSSection_Type">

<vadk:BootArgs> – Kernel boot parameters with static IP.

<vadk:BootArgsDHCP> – Kernel boot parameters with DHCP.

<vadk:BootFiles> – Kernel binary and path to initrd boot script.

<vadk:ISO> – Operating system ISO, MD5 checksum, and packages repository.

<vadk:Distribution> – Operating system distribution details.

<vadk:OSPackages> – Operating system package meta‐groups and packages.

<Section ovf:id="" ovf:version="" xsi:type="ovf:OperatingSystemSection_Type">

ovf:id – This value is defined by an extended version of the DMTF CIM Standard,

CIM_OperatingSystem.OsType. If the default ovf:id value does not correctly reflect the guest OS, consider 105 for 32‐bit or 106 for 64‐bit operating systems.

<Section xsi:type="vadk:ApplicationSection_Type">

<vadk:OSPackages> – Operating system packages.

<vadk:ApplicationPackages> – Application software packages.

<Section xsi:type="vadk:VAMISection_Type">

<vadk:VMToolsCore> – VMware Tools base packages. These packages often come from repositories

on an ESXi host.

<vadk:VMToolsX> – VMware Tools packages to support X windows.

For <new_os>.xsl, verify that the given unattended installer configuration file works for the new guest OS.

For post.xsl, verify that the Linux commands to be executed in this script work for the new guest OS.

The new OS template now appears in the VMware Studio Web interface’s Create a New VM Profile dialog.

Mount the corresponding ISO image under /opt/vmware/www/ISV/ISO so you can start creating profiles and building virtual appliances with the new OS.

To delete the OS template from VMware Studio, go to /opt/vmware/etc/build/templates/<OSname> and remove the related subdirectory hierarchy.

Table 4-2. Support Files in OS Profile

build_profile.xml Template build profile.

<new_OS>.xsl OS unattended installer configuration file.

preinstall.xsl Studio executes this script before installing the OS, to create repositories for packaging utilities.

post.xsl Script executed by Studio inside the VM after the OS installation completes.

commontask.xsl Supplemental to preinstall.xsl and post.xsl scripts.

commonfunc.xsl Supplemental to preinstall.xsl and post.xsl scripts.

VMware, Inc. 39


Fedora 11 As an Example

After creating Fedora 11 based on RHEL 5.4 template, some touch‐up is necessary.

studiocli --newos --osdesc "Fedora 11" --profile /opt/vmware/etc/build/templates/redhat/5/5/build_profile.xml

The kickstart XSL file, in this case /opt/vmware/etc/build/templates/Fedora11/Fedora11.xsl, must

have an %end tag to close the sections %pre, %post, and %packages. RHEL does not require the %end tag.

You also must update the vadk:ISO section of the Fedora 11 profile with the proper vadk:path to the ISO file, and related attributes in this section.

Application PackagesVMware Studio uses the native packaging mechanism for each supported operating system to install and

update software in the virtual machine. RHEL, CentOS, and SUSE use RPM packaging. Ubuntu uses DEB

packaging. VMware Studio includes the mkpkg command‐line tool for creating packages of either type, RPM

or DEB. See Chapter 5, “Packaging a Linux Application,” on page 55 for information about using mkpkg.

VMware Studio supports the automatic conversion of compressed TAR (tar.gz, tgz) files into RPM or DEB files. You can use the VMware Studio Plugin for Eclipse to package your application in a compressed TAR file.

See Chapter 8, “Using the VMware Studio Plugin for Eclipse,” on page 75 for more information.

A build profile contains a list of Application Package Repositories with packages to download from an HTTP

server and install in the virtual machine. You can include external HTTP servers, at some penalty in reliability

and performance. To include additional packages, add either the URL of a directory containing one or more

packages (VMware Studio resolves installation order), the URL of a RPM or DEB package, or the name of a

compressed TAR file.

Before creating a VM, make certain that you have all of the appropriate operating system and third‐party

packages that your application requires. You can install multiple application packages, and you can control

the installation order to define priority in case of package‐file conflicts. Consider these points when you

assemble packages and determine dependencies:

VMware Studio installs packages in the order you give in the Application Package Repositories list

(see Table 4‐6) while resolving and installing any dependent packages.

If you include packages in the Application Package Repositories list that depend on other packages,

VMware Studio resolves dependencies between them and the packages included in the OS ISO.

If your application depends upon packages that are not available in the OS ISO, identify them beforehand.

Dependent packages include system security updates and third‐party packages. If your application

depends upon a specific version of a package that is not present in the ISO, obtain it separately. For

example, your application might depend on the latest version of Apache, but the OS distribution you

select contains an older version of Apache. Place the latest version in the application packages directory

before starting the build process.

By default the Application Package Repositories list contains one URL that refers to a local directory on the

VMware Studio appliance. This URL contains the string [VADK.localIP] to represent the IP address of the local VMware Studio appliance. The following URL and directory path refer to the same location:

URL of the application package repository – http://[VADK.localIP]/ISV/appliancePackages

Local directory on VMware Studio appliance – /opt/vmware/www/ISV/appliancePackages

You can place your application packages in a different local directory on the VMware Studio appliance, or on

another HTTP server. If you supply the URL of a directory or package on another HTTP server, it must be

network‐accessible. Verify that directory indexing is enabled in the HTTP server (for example, Options +Index specified in the Apache configuration file) because VMware Studio requires directory indexing for file discovery.

If your URL points to an HTTP server directory, any .tgz or tar.gz file in that directory is considered to be a package and will be installed.


40 VMware, Inc.

Adding On Demand RepositoriesAn additional repository type for application packages has been included in recent VMware Studio releases.

The ISV user can select the required packages from the repository by specifying their directory in the build

profile vadk:ApplicationPackages element. Studio converts this directory as the new repository.

Example 4-1.

<vadk:url>http://[VADK.localIP]/repo/hier_1-1_i386.rpm</vadk:url><vadk:url vadk:type="ondemand">http://[VADK.localIP]/repo</vadk:url>

This is a required attribute to specify the location of the repositoryʹs package metadata file. If the specified

package has dependency on another package present in the application repository, then VMware Studio finds

the dependent package and adds it to the manifest file.

Creating an On Demand Repository

This section describes how to create an On Demand repository using two example packages called hier and asciimandel. On Demand repositories can be created using RPM for CentOS, RHEL, SLES, and using DEB

for Ubuntu. All the repositories should be placed under the VMware Studio Web root (/opt/vmware/www).

CentOS / Red Hat / SLES

/opt/vmware/www/centos_ondemandhier.rpm (depends on asciimandel)asciimandel.rpm

# createrepo /opt/vmware/www/repo

Ubuntu

/opt/vmware/www/ubuntu_ondemandpool/

hier.debasciimandel.deb

# cd /opt/vmware/www/ubuntu_ondemand# apt-ftparchive packages pool | gzip > pool/Packages.gz

Specifying Packages in Build Profiles

This section describes how to specify On Demand application packages in build profiles.

CentOS

<vadk:ApplicationPackages><vadk:url vadk:path="repodata/primary.xml.gz"

vadk:type="ondemand">http://[VADK.localIP]/centos_ondemand</vadk:url><vadk:url>http://[VADK.localIP]/centos_ondemand/hier.rpm</vadk:url></vadk:ApplicationPackages>

Ubuntu

<vadk:ApplicationPackages><vadk:url vadk:path="pool/Packages.gz"

vadk:type="ondemand">http://[VADK.localIP]/ubuntu_ondemand</vadk:url><vadk:url>http://[VADK.localIP]/ubuntu_ondemand/pool/hier.deb</vadk:url></vadk:ApplicationPackages>

Creating a VM Build ProfileA build profile contains all the required information to automate the building of a VM, including information

about contents of the VM, virtual hardware configuration, location of its OS ISO, and the VAMI management

services to be included. This section lists the steps to create a VM build profile in the Web console. Subsequent

sections provide reference information about the options in each configuration tab.

VMware, Inc. 41


To create a VM build profile

1 Obtain the OS ISO for one of the supported operating systems. See “Operating System ISO Image” on

page 36 for information about supported distributions. You can use a previously built Linux VM as the

starting point, buts the OS ISO image must be present. See “Building with the Import Profile” on page 109.

2 In the VMs tab of the Web console, click Create Profile.

3 In the Create a New VM Profile dialog box, specify a name for your VM build profile, select a profile from

the list, and click Create Profile.

After you build a VM, it also becomes available in the list as a template to create derived virtual machines.

4 The Editing page appears, where you create the build profile of your VM. The Editing page organizes the

build profile into the following tabs:

Description – Specifies general information about the virtual machine or virtual appliance, including

license agreement. See “Description Tab” on page 42 for details.

Hardware – Specifies virtual hardware configuration for the virtual machine, including CPU,

memory, network adapters, CD/DVD, and virtual disks. See “Hardware Tab” on page 43 for details.

OS – Specifies location of the OS ISO image, root password, additional users, and boot script

customization. See “OS Tab” on page 44 for details.

Application – Specifies the application package repository and operating system packages to install

into the virtual machine. See “Application Tab” on page 46 for details.

Management – Specifies VAMI management services to include in the virtual machine, and details

about the optional update service repository. See “Management Tab” on page 46.

Output – Specifies the type of distribution format (OVF, OVA, or ZIP) for the virtual machine.

See “Output Tab” on page 48 for details.

Build Settings – Specifies setup of the build environment, such as connection information to one of

many possible provisioning platforms. See “Build Settings Tab” on page 50 for details.

You can use Next and Back buttons to navigate between tabs until you have specified all required fields.

If you try to navigate to the next page without specifying a required field, an error message appears in red

next to the field where you must fix a problem before continuing. Attempting to navigate off the editing

page produces a confirmation dialog box asking if you want to discard your edits.

Each field in the build profile has a help icon (i in a circle) on the right side. Clicking the help icon toggles

between display of contextual help and a list of frequently asked questions (FAQ).

5 After you complete editing a build profile, you can take one of the following actions by clicking a button

on the right side of the window:

Validate – After completion of a build profile, checks the configuration to help you avoid build errors.

A window appears to show the validations that it performs.

Save and Build – Saves your build profile and displays the Build Summary dialog box for review.

To build the VM and begin provisioning, click Build VM. A progress icon appears with a build log

that shows status as the build progresses.

Save and Close – Saves your build profile and closes the editing page. You can save an incomplete

profile. The build profile appears in the VM List, so you can choose to edit or build it later.

Close Without Saving – Closes the editing page and discards changes. A warning appears asking if

you are sure you want to discard changes made during the current session.

After creating a profile, you can to build the VM. See “Building a VM from the Build Profile” on page 52.

With VMware Studio 2.1 and later, you can run concurrent builds from different VM profiles, or multiple

builds from the same VM profile. The /opt/vmware/etc/studio file governs how many builds can run

concurrently before they start to queue. Setting concurrent_limit higher than two could adversely affect

performance on the provisioning system.


42 VMware, Inc.

With VMware Studio 2.1 and later, you can produce signed OVF distribution files by modifying the signing

script in the XML build profile and specifying a private key file or private key password.

Web Console Tab ReferenceThese sections document all fields in different tabs of the Web Console.

“Description Tab” on page 42

“Hardware Tab” on page 43

“OS Tab” on page 44

“Application Tab” on page 46

“Management Tab” on page 46

“Output Tab” on page 48

“Build Settings Tab” on page 50

Description Tab

Table 4‐3 describes the configuration properties available on the Description tab.

NOTE If you have an existing build profile that you created with earlier versions of VMware Studio, you can

migrate it. See “Migrating Build Profiles from Studio 1.0 or 2.0” on page 53.

Table 4-3. Description Tab Configuration Properties

Field Description

Information

Product Name Name for this virtual appliance or virtual machine. The product name appears in the Web console for the VM and on the welcome screen. Required for VMware Ready.

Version Version number for this release. This field is important if you are shipping the virtual machine as a virtual appliance. The version number is used to track updates and must be in the format of major.minor.build.revision. Numbers can be in the range of 0‐65535. For example, 1.0.0.0 for the first release. Required for VMware Ready.

Full Version This field allows you to enter more descriptive text for version. For example, if the virtual appliance is in the alpha release state, you might enter “1.0.0.0 alpha” version.

Product URL URL on your companyʹs Web site that provides information about the product.

Vendor Name Enter your company name. This field is important if you are shipping the virtual machine as a virtual appliance.

Description Descriptive text about the virtual machine. for example, the features provided or the contents of the virtual machine, and so forth. Placed in the OVF annotation element.

Vendor URL Vendor URL to your companyʹs Web site. This field is important if you are shipping the virtual machine as a virtual appliance.

Application URL URL to your main application contained in this virtual machine. This field is important if you are shipping the virtual machine as a virtual appliance. This URL in used both as a target for the Application URL Label, and in the vSphere summary tab to provide a link to the application. The ${app.ip} keyword in the URL resolves to the VMʹs IP address, after deployment, at runtime. The ${app.ip1.ipv4} keyword in the URL lets the users set the specific IPv4 or IPv6 address for a particular NIC. The following new macros have been included in Studio:

${vami.urlN}, ${vami.ipN}

${vami.urlN.ipv4}, ${vami.ipN.ipv4}

${vami.urlN.ipv6}, ${vami.ipN.ipv6}

VMware, Inc. 43


Hardware Tab

Table 4‐4 describes the configuration properties available on the Hardware tab.

Web Console Visual Customization

Logo Path Location of the image file on the VMware Studio appliance for the icon that displays in the Web console for this virtual machine. This field is important if you are shipping the virtual machine as a virtual appliance.

Logo Link URL The URL to use when the logo is clicked in the Web console. You can specify your company’s Web site or a site that contains information about the virtual appliance. The link should be an http or https URL, for example, http://www.example.com.

Application URL Label The label for the URL in the Application Link URL field. This is the label that appears in the Web console for your application. For example, if your application is named “Acme”, you can use the label “Acme Home” to point to the home address of the Acme application.

Footer Text (no field) To customize the left side footer and the middle footer text, you can edit the XML build profile. See “Customizing the Footer in the Web Console” on page 137.

EULA and Login Screen

End‐User License Agreements You can add an end‐user license agreement (EULA) by clicking the Add EULA button, and more than one EULA by clicking it again. To delete a EULA, click the Remove EULA link associated with the EULA you want to remove.

You can Add EULA multiple times in different languages, then edit the XML profile in /opt/vmware/var/lib/build/profiles to designate the language of each EULA. In the ovf:EulaSection_Type section, change xml:lang="en" to the language’s locale, so vCenter Server can display the EULA in the prevailing locale when importing the virtual appliance as OVF.

EULA The full text of your end‐user license agreement. The user sees this when running the VM for the first time and must accept this license agreement. This is important if you are shipping the VM as a virtual appliance. If no EULA is defined, then the VM boots without user acceptance. If a EULA is defined, but you disable the check box Show EULA on first boot, the appliance does not prompt for EULA acceptance during its first boot.

Login Screen If the Enable Login Screen check box is enabled, the virtual appliance displays the Welcome Text on the login screen after the virtual machine boots up.

Welcome Text on Login Screen Enter information that provides an introduction to your VM. You can supply instructions for the user on how to access your application on the VM, which helps improve the user experience if the VM is shipped as an appliance. You can enter up to 16 lines of text with a maximum of 79 characters in each line. Characters over the maximum line length or lines after the 16th are not displayed. Variable substitutions are accepted for ${app.name}, ${app.version}, and ${vami.url}.

Table 4-3. Description Tab Configuration Properties (Continued)

Field Description

Table 4-4. Hardware Tab Configuration Properties

Field Description

VMware Hardware Version

Hardware Version Sets the virtual hardware version for the VM. For information about virtual hardware version, see the Knowledge Base article 1003746 at http://kb.vmware.com.

Virtual hardware version 4 is for ESX 3 or later, and Workstation 5 or later.

Virtual hardware version 7 is for Workstation 6.5 or later, Player 2.5 or later, Fusion 2 or later, ESX/ESXi 4.0 or later, and vCloud Director 1.0.

Studio supports a maximum of 10 Network Adapters for Hardware Version 7.

Compatibility Shows VMware product platforms compatible with the hardware version selected.

Virtual CPU and Memory

Virtual Processors Select the number of virtual CPUs. The number must be less than or equal to the number of CPUs in the provisioning platform used to create the virtual machine.

http://kb.vmware.com/kb/1003746


44 VMware, Inc.

OS Tab

Table 4‐5 describes the configuration properties available on the operating system OS tab.

CPU Reservation (Mhz) Guaranteed lower bound on the amount of CPU that the host reserves for this VM.

Memory (MB) The amount of virtual memory (in megabytes) allocated to this virtual machine. Enter a value in 4 MB increments (4, 16, 256, 512 and so on). The default for most Linux virtual machines is 256MB. The default is 512MB for RHEL 5.5 (32‐bit or 64‐bit). This amount of memory must be less than or equal to the memory of the provisioning platform.

Memory Reservation (MB) Guaranteed lower bound on the memory amount that the host reserves for this VM.

Virtual Devices

Network Adapters Number of virtual network adapters to be configured for this VM. The VAMI agent provides console and Web console interfaces to manage all the network adapters defined by the user.

The number of network adapters is a drop‐down menu with a maximum 4 of NICs using hardware version 4 or a maximum of 10 NICs using hardware version 7.

VAMI can now manage multiple network interfaces. User can specify logical names to the network adapters by modifying the OVF file. If the logical names are not specified, then Studio provides Network 1, Network 2 as the default network names.

CD/DVD Drives Number of optical disc drives to be configured for this VM.

Virtual Hard Disks

Name Name of the virtual disk, used when naming VMDK files.

Size (GB) Size in gigabytes of the virtual disk, as a floating point number with two optional decimal places, for example 2.33, 4.6, or 5.

If you require only one hard disk, you may change the disk size, but you should not alter values in the Partitions section. On Linux the /boot partition must come first. Adding or removing partitions in the first hard disk is not recommended. Click the Modify Disk Layout link to alter the Partition specifications.

If you require more than one hard disk, click the Add Disk button.

To remove an additional virtual disk, click the Remove Disk link.

LVM (check box for added disk) Check this box to indicate that you would like this disk to be managed by the Logical Volume Manager software in the operating system. This software allows you to increase the disk size at a later time.

Partitions

Mount Point Mount point for the partition.

Maximum Size Check the box to specify that this partition automatically uses the maximum size available. Only the last partition of a disk should be marked as Maximum Size.

Size (MB) Size in megabytes of the partition.

Filesystem File system format, either ext3 or swap.

Only ext3 is supported at this time. The swap partition must be on the first disk, for compatibility with unattended installers.

Bootable Check this box if you want to be able to boot from the partition.

Table 4-4. Hardware Tab Configuration Properties (Continued)

Field Description

Table 4-5. Operating System Tab Configuration Properties

Field Description

Operating System

OS Distribution A read‐only field specifying the operating system corresponding to the template you chose when you created this virtual machine.

VMware, Inc. 45


ISO URL The location of the OS ISO image. The URL can be either a file:// or http:// location. It is recommended to use file:// to a local OS ISO file.

If VMware Studio warns you that the “ISO Location Cannot be Verified,” download the required OS ISO image or NFS mount the OS ISO directory, then click the Check Now button to reverify the ISO image at this URL.

ISO MD5 The MD5 checksum for the OS ISO image. VMware Studio compares the value in this field with the checksum for the ISO image to ensure that the image is correct.

In VMware Studio 2.1 and later you can edit this field to correct the checksum after updating or altering the ISO image. Also, removing the checksum entirely skips the checksum validation step. This is not generally recommended, but can be helpful if you have a customized ISO image.

User Accounts

Root Password Enter the password of the administrative user account for the virtual machine and then confirm the password by entering it again in the Confirm Password field. If you are shipping the VM as virtual appliance, you might want to create a first boot script to prompt users for a new root password.

If there is an error during the appliance build, and the build scripts did not have a chance to set the root password to what was specified in the build profile, then Studio will follow the following algorithm to set the root password in the failed appliance VM. If you set the password type in the profile to plaintext, it becomes the password in the appliance. If you set the password type in the profile to base64, it becomes root in the appliance to avoid confusion.

Add User If you need to add a user account, click the Add User button. The VAMI agent is using the operating system’s database to authenticate access to the Web console and the small footprint CIM broker (SFCB).

Username Enter the name for this user account. For virtual appliances, you may want to create non‐root user accounts for limited access. A user must belong to the vami group to be able to use the VAMI UI in an appliance. User does this by selecting the vamiAdmin checkbox during build process. This will put the user into the vami group.So, for example, in the /etc/group file:

vami:x:1002:root

the root user is a member of the vami group.

Password Enter the password for the user and then enter it again to confirm the password.

Full Name (optional) Enter the full name for this user account.

UID (optional) Enter User ID of this user account. Generally, not specifying the UID and allowing the OS to determine the UID is recommended. If specified, make sure to give a valid (existing) UID number value that is unique within the VM.

VAMI Admin (optional) Check box to give this user VAMI administration privileges (allowing this user to log in to the VAMI web interface).

Remove User To delete a user you have added, click the Remove User link.

Boot Customization

Enable Boot Scripts If the check box is enabled, the first script runs at initial boot and the other script runs at subsequent boots.

First Boot Script A script that contains any application‐related configuration that should occur when the virtual machine is first booted up. Important for virtual appliances where end‐user configuration is required according to the deployment environment. For example, populating a database, configuring system data that the application needs, or starting various application components. This script is executed only on the first boot up of the virtual machine. This script can be found in the virtual machine at /opt/vmware/etc/isv/firstboot.

Subsequent Boot Script A script to run on the second and subsequent reboots of the virtual machine. You can enter commands for application startup in this field. You can locate this script in the VM at /opt/vmware/etc/isv/subsequentboot.

Table 4-5. Operating System Tab Configuration Properties (Continued)

Field Description


46 VMware, Inc.

Application Tab

Table 4‐6 describes the configuration properties available on the Application tab.

Management Tab

Table 4‐7 describes the configuration properties available on the Management tab.

VAMI management services expose management functionality as tabs in the generated appliance’s VAMI Web

console. The Core service provides the VAMI user interface and server framework. The System and Network

services provides basic system information, time zone settings, and network settings. The Update service is

optional and enables updating of the OS and application packages from a remote update repository.

There are now 64‐bit compiled VAMI binaries to go with the 64‐bit operating systems that Studio supports.

Table 4-6. Application Tab Configuration Properties

Field Description

Application Packages

Application Package Repositories A list of Application Package Repositories.

If you place packages into this directory, you need to specify only the directory, not each package explicitly.

Use the Move Up and Move Down buttons to specify the installation order.

Add URL | Edit | Remove To add an application package or directory of application packages to your VM, click Add URL, enter the URL of the package or directory, and click OK.

To change the URL of an application package or directory, click Edit, modify the URL, and click OK. To delete an entry, click Remove.

See “Application Packages” on page 39 for details of application repositories.

VMware Tools

Install base packages If this check box is enabled, the VMware Tools at the listed package location will be installed.

Install packages for X If this check box is enabled, the VMware Tools for X11 windows at the listed packages location will be installed.

List of packages from OS install media

Package, Version, Arch, Description A list of packages from the OS installation media to include in the virtual machine. When you select a package in the list, a description of it appears on the right.

Add | Remove The OS ISO image contains additional packages that can be installed into the virtual machine. VMware Studio provides a selection dialog box to help you find application packages in the OS ISO image.

To add packages to the list, click Add, search for a package by typing part of its name in the Search window or selecting a category, click Add on packages to add, and when you are ready click OK.

To remove a package from the list, select it and click Remove. You cannot remove any VAMI‐required packages from the list.

Application Installation Customization

Application Pre‐Install Script Script that runs after installation of packages from the OS media, but before the installation of application packages during virtual machine provisioning.

Application Post‐Install Script Script that runs after the installation of application packages during the virtual machine provisioning phase.

Table 4-7. Management Tab Configuration Properties

Field Description

Management Services

Enable Management CIMOM Server

If you enable this check box, the small footprint CIM broker (SFCB) that supports VAMI is installed. SFCB is a type of CIMOM (CIM object manager).

If this check box is disabled, as a side‐effect the management UI is not installed.

VMware, Inc. 47


core, network, system Name, version number, and description of included management services. Services appear as tabs in the Web console of a VM built by VMware Studio, if you enable the UI. You can delete services that you create, but built‐in services are mandatory.

Services are defined in the /opt/vmware/var/lib/build/services hierarchy.

Linux Management Services are also displayed under the Library > Linux tab, where you can import a new service

Add | Remove To add a service, click the Add button, select its checkbox, and click OK. In particular, you can select the VAMI update service here.

To remove a service, select its checkbox and click the Remove button.

To replace a service with a newer version of the service, first remove the old version, then add the new version.

Some of the management services are required and can be replaced only by a different version of the service.

Management Web Server Settings

Enable Management Server (UI) If this check box is enabled, management services appear as tabs in the VAMI console of a VM built by VMware Studio, available with HTTPS.

Web Server HTTPS Port Configurable HTTPS port number for the VAMI Web console. Change this number if the application you are building requires this port number. Default port is 5480.

Customize GUI Tab Order You can reposition a tab in the generated VAMI Web console UI.

SSL Certificate Information

Common Name This information is used to create a self‐signed SSL certificate for the virtual machine Web console and the small footprint CIM broker (SFCB) during the first boot.

Server certificates are issued to a common name. In most cases, this is the full DNS name (fully qualified domain name) used to navigate to a Web site.

Organization The full legal name of your company. This name is used to sign the certificate.

Unit The group or department within your company requesting the certificate.

Country Code Enter the two‐digit code for the country where your company is located. For example, US for the United States.

Update Service Repository Settings (Optional)

How to enable update service: Update service enables remote updating of a VM. Update service is initially disabled for builds, but is recommended when distributing virtual appliances to end‐users. To enable Update service and establish an update repository, follow this procedure.

Under Management Services, click Add, select the update checkbox, click Add again, and fill out all fields for the update repository service.

See Chapter 7, “Managing a Linux Update Repository,” on page 67 for more information about update repositories.

CDROM updates If you want to create a CDROM containing updates for appliances that lack external network access, select this button. You will be able to deliver the ISO archive burned onto the CDROM, and your appliance will be able to update from the CDROM.

Repository URL If the Specify repository button is selected instead of the CDROM updates option, Repository URL specifies location of the update repository. The Repository URL goes into the build profile and gets embedded in the virtual appliance, which periodically checks the URL for updates. If you plan to provide updates for a virtual appliance, the Repository URL must point to an Internet accessible location, and you should not change the URL after a build.

You might plan to use a staging server for internal testing and copy the contents of your update repository manually to an Internet accessible and externally visible site when the virtual appliance is ready to be shipped.

Username (optional) This user name is used to authenticate to a Web server at the URL for the update repository. To comply with licensing restrictions, this field is required for updating any virtual appliance based on the Red Had Enterprise Linux (RHEL) operating system. All customers use the same user name to download updates.

Table 4-7. Management Tab Configuration Properties (Continued)

Field Description


48 VMware, Inc.

Output Tab

Table 4‐8 describes the configuration properties available on the Output tab.

Password (optional) Password for the specified user name. Enter the same password twice to confirm.

This password is used to authenticate to a Web server at the URL for the update repository. To comply with licensing restrictions, these fields are required for updating any virtual appliance based on the Red Had Enterprise Linux (RHEL) operating system. All customers use the same password to download updates.

VendorUUID A unique identifier that VMware vCenter Update Manager uses to identify a vendor. All VMs created by a particular vendor should have the same VendorUUID. VMware recommends that this be a 128 bits long UUID (16 bytes).

ProductRID A unique identifier that VMware vCenter Update Manager uses to identify a particular product. Each Product should have a different ProductRID. VMware recommends that this be a 128 bits long UUID (16 bytes).

Update Description Description for this update. For example, the base version number, issues fixed, or enhancements provided. Update information typed here appears in the Web console of the virtual appliance when the update is made available.

Repository Server Settings

File Transfer Protocol A read‐only field indicating use of SCP file transfer protocol.

File Transfer Hostname The host name or IP address where the update repository is located. VMware Studio must have SSH/SCP access to the host that serves as the update repository. This is needed to publish the virtual appliance file to the update repository.

File Transfer Username User name on the update repository host. Used by VMware Studio to copy files using the SCP protocol to the update repository staging server. This user name can be different from the user name that the virtual appliances uses to download updates.

File Transfer Password Password for user on the update repository host. Type it twice to confirm.

File Transfer Path Path used for publishing virtual appliance updates to the update repository. For the virtual appliance to find any updates, this path should translate to the URL of the update repository.

Repository Export Settings

Update Archive Enable this option to export an update archive as a ZIP file, and specify ZIP Filename. The exported archive is placed in the build instances directory. You can later copy this ZIP archive to a Web server.

ISO Archive Enable this option to export an update archive as a ISO file, and specify ISO Filename. The exported ISO image is placed in the build instances directory. You can later copy this archive to a Web server, or more likely, burn it onto CDROM.

Table 4-7. Management Tab Configuration Properties (Continued)

Field Description

Table 4-8. Output Tab Configuration Properties

Field Description

Distribution Format

Output File Name The name for the distribution file of your virtual machine. This name is used when creating the virtual machine OVF, OVA, or ZIP package.

Output Format Select the type of distribution file for the virtual machine. The default format is OVF. You can choose more than one output format.

OVF – Use this format if the virtual machine will be deployed on virtualization platforms that support the Open Virtualization Format.

OVA – Archive of OVF 1.0 descriptor and VMDK virtual disk files. Requires VMware vSphere 4 for deployment.

ZIP – Use this format if your virtual machine will be deployed on virtualization platforms that do not support OVF.

Directory in ZIP Archive The directory under which files related to your virtual machine should appear within the generated ZIP output file.

VMware, Inc. 49


Enabled IP Protocols

IPv4 By default IPv4 is always selected, so this check box is grayed out.

IPv6 Click this setting to use IPv6 address format. Studio does not support IPv6‐only network environments.

OVF Environment

IP Address Deployment Choices (in vCenter)

Do not prompt for any networking parameters

Click this button to avoid asking the vSphere administrator at deployment time to provide network parameters, which will be set from DHCP, or failing that, manually. This option prevents VMware Studio from automatically generating any OVF networking properties.

Prompt for all networking parameters

Click this button to have the vSphere administrator set all networking parameters when installing a VM through vCenter Server. This option instructs VMware Studio to automatically generate OVF networking properties.

Prompt for an IP address, and retrieve additional parameters from an IP Pool

Click this button to prompt the vSphere administrator with networking parameters based on the IP Pool, using either DHCP, a specific fixed or transient address, or both. When you click this button, two choices appear underneath, as described below.

DHCP (check box) During deployment the administrator is given the option to use a DHCP server for setting up the VM, and networking is automatically configured by the VAMI agent.

Fixed or Transient (check box) During deployment vSphere gives the administrator the option of a fixed or transient IP address for the VM. Networking is automatically configured by the VAMI agent. This requires OVF 1.0 or OVA, and an IP Pool configured on the vCenter Server.

OVF Environment Access Options

OVF Environment Access Mode The guest can access the OVF environment through VMware Tools or by CDROM. The default access is by VMware Tools, which requires VMware Tools to be installed in the guest. At least one OVF environment access mode must be enabled for network auto‐configuration to execute at boot time. If you select CDROM access mode, the OVF environment is read from the mounted disc attached by vCenter.

OVF Properties

Add | Edit | Remove Click Add to add an OVF property. Click Edit to change an existing OVF property. Click Remove to delete an OVF property.

Key Key to OVF Property.

Label Label for OVF Property.

Description Description of OVF Property.

Type List of OVF property types supported for editing. These types are enforced by VMware vSphere during deployment. If you select Custom Type, ovf:type appears with value and qualifiers.

Default Value String, unsigned integer, string choice, Boolean value, or IP address of this property.

Maximum Length Maximum length that can be specified for a string property.

Range Low and high values that can be specified for an integer property.

ValueMap List of possible values for a string choice property.

User Configurable Whether to prompt user to allow changing of property.

ovf:type Each Property element in a ProductSection must be assigned an ovf:type attribute. Valid types look like C data types and are listed in the OVF specification.

ovf:value Optional attribute ovf:value provides a default value for a Property element.

ovf:qualifiers Optional attribute ovf:qualifers specifies CIM type qualifiers for a Property, with multiple qualifiers separated by commas.

vmw:qualifiers Optional attribute vmw:qualifers gives VMware‐specific qualifiers for a Property.

Table 4-8. Output Tab Configuration Properties (Continued)

Field Description


50 VMware, Inc.

Build Settings Tab

Table 4‐9 describes the configuration properties available on the Build Settings tab.

Build settings are used only for provisioning a VM. They are not the deployment configurations of the output

VM. The output VM (except OVF and OVA, which can override network settings) will be configured to run at

first in DHCP network mode.

Table 4-9. Build Settings Tab Configuration Properties

Field Description

Build Environment

Virtualization Platform The VMware virtualization platform that will provision (build) the virtual appliance. A drop‐down menu displays a choice of virtualization platform, including ESX/ESXi, vCenter Server, vCloud Director, and Workstation. As you select different platforms, build environment settings change. All settings are documented below, although not all appear at any given time.

Connection Wizard Click the Connection Wizard button for help configuring this page. You can use it to configure the build environment settings. It allows you to browse a host and select the necessary settings. The connection wizard is available for ESX/ESXi hosts, VMware VirtualCenter, VMware vCenter Server, and vCloud Director 1.0.

Build Environment Settings

<Platform> Host The host name or IP address of the virtualization platform you use for provisioning.

Not all information items are required for different platforms. For example, only VMware Workstation needs the vmrun command, and the build directory path is needed only for hosted products.

Port The port for communicating with the remote host that performs provisioning. For many virtualization platforms this is the HTTPS port 443. VMware Workstation uses SSH on port 22 for remote provisioning, so it does not ask for a port number.

Username A user name on the remote host for authentication of virtual machine provisioning.

Password Password for the specified user name. You must type the password twice to confirm.

Datacenter Name (vCenter only) Datacenter name as designated in the VMware vSphere inventory. This name appears in the left sidebar of the VMware vSphere client when connected through vCenter Server.

Datastore Name Specify the datastore where you want to store the virtual machine files. Datastore names appear on the VMware vSphere client Summary page.

Resource Pool (Optional) If you created a resource pool and you want the VM to be build in this resource pool while being provisioned, you can specify the resource pool name.

ESX/ESXi hosts and vCenter Server have a built‐in default resource pool, Resources. This resource pool is visible in the Managed Object Browser (MOB) interface at http://<esx-or-vc>/mob, but the vSphere Client, VMware Studio, and ovftool do not support it. If you want to set a resource pool, use one that was created, not Resources.

Managed Host/Cluster (vCenter only) Host name or IP address of the ESX/ESXi host managed by vCenter.

Network Label Specify the network connection label. Network name appears in the VMware vSphere client Summary page. By default this name is VM Network.

Host Host name of the VMware vCloud Director.

Organization Name Organization name in the vCloud Director.

Username User name to authenticate the organization in vCloud Director.


Organization Catalog Name of the organization’s catalog, this is applicable only for vCloud Director.

Organization VDC Name of the organization’s virtual datacenter, applicable only for vCloud Director.

Organization Network Name of the networks accessible by the organization, applicable only for vCloud Director.

VMware, Inc. 51


Path to vmrun Command (Workstation only) VMware Workstation uses the vmrun command for provisioning. Do not include the vmrun command itself, only the path to it.

On Windows this could be C:\Program Files\VMware\VMware Workstation.

On Linux this could be /usr/bin.

Build Directory Path (Workstation) The temporary path used by the provisioning platform to register and control provisioning of the virtual machine. This location is used to store the virtual machine during the provisioning phase.

For example, if a Linux system is the host of the VMware Workstation and /tmp is the provisioning directory, then enter /tmp in the Host Path field.

As an alternate example, if a Windows system is the host of the VMware Workstation and c:\tmp is the provisioning directory, SCP uses the OpenSSH server in Cygwin, so the Host Path is c:\tmp but the File Transfer Path below should be /cygdrive/c/tmp.

Host Environment (Workstation) Specifies the host operating system where your provisioning platform runs. If you select Windows or Linux Custom Settings, then you must fill in the following items for File Transfer. See the descriptions of these items under the Output tab.

File Transfer Protocol

File Transfer Username

File Transfer Password

File Transfer Path – Used by VMware Studio for uploading the virtual machine being built to the Host Path. To upload the virtual machine during the provisioning phase from VMware Studio to the host running the provisioning platform, you might need to specify the File Transfer Path and Host Path differently for the scp utility, although they must refer to the same directory on the host running the provisioning platform. For instance, if VMware Workstation runs on Windows, SCP uses the OpenSSH server in Cygwin, so the Host Path is c:\tmp but the File Transfer Path should be /cygdrive/c/tmp.

Network Settings

Network Type This controls how to set network addressing for the transient virtual machine that is built during provisioning. Specify DHCP IPv4 to retrieve IP address and network settings from a DHCPv4 server. Specify Static IPv4 to set a fixed IP address. (DHCPv6 and Static IPv6 might also appear in the drop‐down menu.) If you specify Static IPv4, the following fields appear for you to fill in:

IP Address

Netmask

Gateway

Preferred DNS Server

Alternate DNS Server

Network Connection For VMware Workstation, specify one of the following options:

Bridged mode is the default for communicating with the virtual machine being built. Bridged mode is required when the VMware Studio virtual appliance and the provisioning platform are running on different computers.

Host Only mode applies when VMware Studio is running on a local installation of the provisioning platform. For Host Only provisioning a virtual appliance must be configured to use Host Only networking by powering off the VMware Studio virtual appliance and editing its virtual network adapter settings.

Build Agent

Remove agent after provisioning If this check box is enabled, the management agent is removed after provisioning. VMware recommends that you retain the build agent when testing a VM or when using it as a base for other VMs. VMware recommends that you remove the agent for a production VM.

Table 4-9. Build Settings Tab Configuration Properties (Continued)

Field Description


52 VMware, Inc.

Building a VM from the Build ProfileAfter you complete a build profile, you can build a VM from it. First click Validate to verify profile contents.

If the VM profile validates, click Save and Build. Then in the Build Summary dialog box, click Build VM. This

starts building a transient VM on the provisioning platform.

To retain the transient VM without cleaning up after the build, in the Build Summary dialog box, click

Advanced Build Settings. This makes visible a check box saying “Retain transient VM on the virtualization

platform and skip provisioning cleanup.” Clicking the check box allows you to test the VM on the provisioning

platform before deploying it elsewhere.

When the build starts, a status icon appears to indicate that the build is in progress. As provisioning continues,

a build log appears to inform you of each completed step in VM provisioning. To eventually cancel a build in

progress, click Cancel under the status icon.

You can launch multiple builds concurrently: navigate to another build profile and click Save and Build again

(assuming that build has completed). You can create and build a new profile while a build is in progress.

The Linux VM always reboots before application install. If you encounter problems during the build process,

see “Troubleshooting VM Builds” on page 145 for diagnostic information.

After a build, you can view various logs to see what happened during the build. In the list of VM profiles, select

a VM and click Build Log to see a recap of build progress.

To see the build summary, various logs, and discovery reports: in the VM List, click the VM name > Finished

(or Failed, or Canceled). The Details dialog box appears, with the following tabs:

Build Summary – provides details of the build profile configuration.

Verbose Log – provides a detailed log of each completed phase of the build process.

Debug Log – provides details of each completed build phase, including debugging information.

Application Install Log – provides a log of the installation messages as the operating system and each

application package gets installed into the virtual machine. Reviewing the install log can help when

troubleshooting package dependency errors if more packages are required.

Discovery Reports – provides information about packages, hardware settings, and operating system.

Each build is stored in the VMware Studio appliance’s file system. You can delete older builds when they are

no longer needed. See “Reiterating the Build Process” on page 53 for more information.

Testing the Generated VMAfter you have successfully built a VM, you can obtain the virtual machine distribution file by clicking on the

ZIP or OVF link (depending upon which type of output file you specified) in the Download column of the

VM’s Previous Build list.

You should click on your virtual machine distribution file and test the completed VM by deploying it in its

intended environment to ensure that the VM and any applications that it contains work properly. You can

download a ZIP file for testing. Do not download an OVF for testing, because if you do, you get only the OVF

and not the associated VMDK files. Instead, test the OVF by right clicking on the URL, copying it, and pasting

it into the Import Appliance or Deploy OVF Template dialog boxes of ESX 3.5 or later, respectively.

Verify that all application packages are installed correctly and that your boot scripts run correctly. Check that

your application starts correctly.

If you plan to distribute this virtual machine as a virtual appliance to your customers, see the User’s Guide to

Deploying vApps and Virtual Appliances for information about deployment of a virtual appliance.

IMPORTANT With vSphere, you can monitor the OS build and application install on the provisioning server.

After prebuild, a thumbnail of the server console appears, refreshed every 5 seconds, alongside the build log.

For a full‐size image, click on the thumbnail. Watching a build helps greatly if something goes wrong.

VMware, Inc. 53


Reiterating the Build Process

Many developers find that an easy way to a create a Linux VM is to build it initially containing only the

operating system, then add application packages and dependencies in successive builds. Each successful build

occupies space, but you can delete them.

To delete a build using the VMware Studio console, select a VM from the VM List, locate the build instance

you want to remove, and click Delete. You can also delete a build using the studiocli -d command.

VMware Tools Installed in a Generated VM

As of VMware Studio 2.6, VMware Tools are no longer specifically managed by the VM. Instead of using a

generalized version, or a VMware Tools version from elsewhere, the VM now uses the official release of

VMware Tools presented by the virtualization platform when asked to install VMware Tools. Therefore ESXi

and vCenter no longer consider the tools to be “3rd party/independent” (as listed in the vSphere Client). They

are full‐fledged VMware Tools with a version number, and are now reported as “Running (Updated)” in the

vSphere Client. This change was based on customer requests and was also required for vCloud Director.

A virtual appliance user can now update VMware Tools when desired by running Install VMware Tools on

the virtualization platform.

Newly released operating systems might not yet be supported by the official VMware Tools presented by the

virtualization platform, especially on older ESX/ESXi hosts. New VMware Tools versions and guest packages

are called Operating System‐specific Packages (OSP) and posted to http://packages.vmware.com/tools/esx/

soon after they become available. You can download these VMware Tools for a specific OS if needed.

Another alternative is to obtain and compile the open‐source tools at http://open‐vm‐tools.sourceforge.net.

Despite the similar names, the OSP vmware-open-vm-tools packages are not the same as the open‐source

VMware Tools produced from SourceForge code.

If an OSP package or open‐source tools was installed in a VM, users can run the dpkg or rpm command to

manually uninstall the vmware-open-vm-tools* DEB or RPM package, then run Install VMware Tools from the virtualization platform, or install a new version of the vmware-open-vm-tools* DEB or RPM package.

Migrating Build Profiles from Studio 1.0 or 2.0You can import build profiles into VMware Studio in the following circumstances:

When you upgrade to a newer version of VMware Studio.

When you manually create a build profile.

When using a build profile created by someone on another VMware Studio appliance.

If you have an existing build profile that you want to bring into VMware Studio, you can import the profile.

However you cannot use, nor successfully import, a Studio 2.0 Beta profile into Studio 2.0 or 2.1 GA. Instead,

you must start from a pre‐existing 2.0 template, or import a VMware Studio 1.0 profile.

NOTE The SIF feature in the VMware Studio 2.5 release is useful for exchanging build profiles and other

virtual appliance artifacts from one VMware Studio appliance to another.

To import an existing build profile

1 Place the build profile on the host where the Web browser runs.

2 Open the VMware Studio Web console to the VMs page and click Import Profile.

3 A dialog box appears where you enter a name for the profile and location of the build profile to import.

Click the Browse button to help find the build profile on your computer.

4 Click Import Profile. VMware Studio creates a new build profile based on the imported one, and adds it

to the VM List. You can select the newly imported VM and build it, or edit its profile.

http://open-vm-tools.sourceforge.net


54 VMware, Inc.

VMware, Inc. 55

5

This chapter contains the following sections:

“VMware Studio Make Package (mkpkg) Tool” on page 55.

“Operating System Native Tools” on page 58.

“TAR Archive as Input Format” on page 59

“Operating System Footprint Reduction” on page 60

“Just Enough Operating System” on page 60

VMware Studio Make Package (mkpkg) ToolYou can provide application bits in various formats to be installed on a virtual machine. If you have a binary

image of your software, you can specify copy commands as part of your pre‐install or post‐install scripts.

You can also specify the application bits in TAR format.

For better lifecycle management of the virtual machine contents, VMware recommends that your application

be packaged in the native packaging format of the operating system, RPM or DEB. Packaging in native format

lets you update the more easily in the future. Automatic updates, version tracking, dependency resolution,

and complete virtual appliance manifests are the benefits of requiring that applications be delivered in the

native operating system packaging format.

VMware Studio provides the mkpkg command line tool to assist in the creation of application packages. Using

the mkpkg tool you can create either DEB or RPM application packages. In addition, the VMware Studio Plugin

for Eclipse is capable of creating packages, in a way equivalent to mkpkg. For more information, see Chapter 8,

“Using the VMware Studio Plugin for Eclipse,” on page 75.

Options of the Make Package Tool

The following list shows the Linux operating systems that VMware Studio supports, and the package format

for each operating system:

CentOS – RPM

RHEL – RPM

SLES – RPM

Ubuntu – DEB

For DEB packages, you create and specify the pre‐install and post‐install scripts when you build the package.

These scripts remain separate files with DEB packages.

For RPM packages, the pre‐install and post‐install scripts are embedded into the control.spec file. Because the pre‐install and post‐install scripts are inserted into the generated template control.spec, you must

specify the scripts when you run mkpkg -t rpm -T.

Packaging a Linux Application 5


56 VMware, Inc.

The mkpkg command syntax, with options described in Table 5‐1, is as follows:

mkpkg -t {rpm|deb} [-T] [-c ctrl] [-C file] [-P preinst] [-p postinst] [-R prerem] [-r postrem] <dir>

This is the same as running mkpkg from the studiocli front‐end.

studiocli --mkpkg -t {rpm|deb} [-T] [-c ctrl] [-P preinst] [-p postinst] [-R prerem] [-r postrem] <dir>

Example of Creating a DEB Package

Before you create a DEB package, you must organize your application packages into the proper directory

structure. For example, executable files in /bin must be under a subdirectory named bin and files that belong in /etc should be under a subdirectory named etc.

Hadoop, an open‐source distributed file system for large data‐sets written in Java, is our example here.

To create a DEB package for Hadoop

1 On the VMware Studio appliance, choose or create a directory and extract Hadoop into it.

cd /<your_dir>tar zxpf hadoop-0.20.0.tar.gz

2 Create a Control file by running this command, which produces the message that follows.

mkpkg –t deb –Tdeb control file template has been created as “control”

3 You can now modify the control file as needed.

Package: hadoop-dfsVersion: 1.00Essential: yesPriority: extraSection: utilsMaintainer: [email protected]: i386Description: Hadoop is a distributed file system based on map-reduce.

Table 5-1. mkpkg Options

Option Description

-h Display help in short format.

-H Display help in verbose format.

-t Type of package to create (rpm or deb). Mandatory argument.

-T Creates a sample control file to be used as a template for the package type.

-c Package control file. You can create a sample control file to use as a template with the -T option.

-C File containing a list of user configuration files that are not overwritten when a package is upgraded.

-P Pre‐install script to be run before installing the package.

-p Post‐install script to be run after installing the package.

-R Preremoval script to be run before removing the package.

-r Postremoval script to be run after removing the package.

<dir> The directory to be packaged. Programs and files in this directory should be in their proper place when installed, relative to this directory. For example, a file that should be installed into the /etc directory should be put into a subdirectory called etc in this directory.

NOTE The control file also contains a Depends section. If you do not have any package dependencies,

make sure you remove the Depends section.

VMware, Inc. 57

Chapter 5 Packaging a Linux Application

4 You can create pre‐install, post‐install, preremoval, and postremoval scripts for your application.

These scripts can contain commands that you would run while installing your application. In this

example we name our pre‐install and post‐install scripts preinst and postinst. Similar naming could

be followed for the preremoval and postremoval scripts. Run the following command:

mkpkg –t deb –c control –P preinst.sh –p postinst.sh hadoop-0.20.0

If your command syntax is correct, you get a message similar to the following:

109737 blocksdpkg-deb: building package ‘hadoop-dfs’ in /<your_home>/hadoop-dfs-1.00_i386.deb’

5 Copy the generated DEB file to /opt/vmware/www/ISV/appliancePackages with the cp command:

cp hadoop-dfs_1.00_i386.deb /opt/vmware/www/ISV/appliancePackages

Example of Creating an RPM Package

Before you create an RPM package, you must organize your application packages into the proper directory

structure. For example, executable files in /bin must be under a subdirectory named bin and files that belong in /etc should be under a subdirectory named etc.

SugarCRM, an open‐source software solution for customer relationship management, is our example here.

To create an RPM package for SugarCRM

1 On the VMware Studio appliance, choose or create a directory and extract SugarCRM into it.

cd /<your_dir>unzip SugarCD-5.1.0c.zip

2 Create a Control file by running this command, which produces the message that follows

mkpkg –t rpm –T -p postinst.sh rpm control file template has been created as “control.spec”

Unlike for DEB, mkpkg for RPM places the pre‐install and post‐install scripts within the control file.

3 You can now modify the control.spec file as needed.

Summary: Sample SugarCRM packageName: SugarCRMVersion: 5.1.0cRelease: 11License: CommercialVendor: SugarCRMGroup: System Environment/DaemonsURL: http://www.sugarcrm.comBuildArchitectures: noarch#Requires:%description

The following is an example of a SugarCRM package:

%post#!/bin/bashchown -R wwwrun /opt/SugarCE-Full-5.1.0c/## Do not put anything below the %defattr line; the list of files# in this package is automatically written there.#%files%config /opt/SugarCE-Full-5.1.0c/config.php%defattr(-,root,root)

The %config section lists configuration files that you do not want overwritten during an update.


58 VMware, Inc.

4 Run mkpkg with the control.spec file you just edited.

mkpkg -t rpm -c control.spec SugarCE-Full-5.1.0c

If your command syntax and dependencies are correct, you see messages similar to the following before

your RPM is generated:

109737 blocksProcessing files: SugarCE-Full-5.1.0cChecking for unpackaged file(s): /usr/lib/rpm/check-filesWrote: /<your_home>/ sugarcrm_5.1.0c.0-11_i386.rpm

5 Copy the generated RPM file to /opt/vmware/www/ISV/appliancePackages with the cp command:

cp sugarcrm_5.1.0c.0-11_i386.rpm /opt/vmware/www/ISV/appliancePackages

Operating System Native ToolsIf you choose to use native tools of the operating system instead of mkpkg, the following sections provide a

brief overview of how to package an application in DEB or RPM formats.

DEB Native Packaging

DEB packages are constructed by writing a small control file and pointing the packaging tool at a directory

hierarchy that contains only the application files installed in their proper order.

A control file can be simple, for example:

Package: change-this-package-nameVersion: 99.99Essential: noPriority: extraSection: utilsMaintainer: [email protected]: i386Description: This describes the package, and contains a summary if what it provides.

The command to generate the package is dpkg-deb. Because of file permission issues, you usually call it from

a command called fakeroot, as in this example:

fakeroot dpkg-deb -b <directory-hierarchy>

RPM Native Packaging

RPM packages are constructed similarly to DEB‐based packages, but in addition to pointing the packaging

tool at a directory containing the application’s files, each file in the application must be referenced in the

package control file, as in this example:

Summary: This is the short description of the package.Name: change-this-package-nameVersion: 99.99Release: 99.99License: CommercialVendor: Your Company NameGroup: System Environment/DaemonsURL: http://YourCompanyURLBuildArchitectures: noarch%descriptionThis is the longer description of the package,and should contain more detailed informaton aboutwhat the package provides.

%files%defattr(-,root,root)/bin/ls

The command to generate RPM packages is rpmbuild, which you run as in this example:

rpmbuild -bb <controlfile> --buildroot <directory-hierarchy>

VMware, Inc. 59

Chapter 5 Packaging a Linux Application

TAR Archive as Input FormatAs an alternative to RPM and DEB packages, applications can be installed using TAR files as input. To use this

feature, add the TAR file to an application package repository. VMware Studio converts the TAR file to an RPM

or DEB (depending on the OS native package format) during installation of the OS, and installs as a normal

RPM or DEB file. If enabled, the update repository is also populated with the RPM or DEB file.

The TAR file should follow one of the following format specifications.

1 Simple package with no version, no metadata, and no updates:

a Name the TAR file <packageName>.tar.gz or <packageName>.tgz

b The RPM and DEB package will be version 1.0.0, and can be installed on a Linux OS.

c VM updates will not install new versions of the package.

d Contents of the TAR file will be installed into the root directory of the resulting VM.

2 Package with version, but no other metadata, updates if version increments:

a Name the TAR file <packageName>_<version>.tar.gz or <packageName>_<version>.tgz

b The RPM and DEB package will have a <version> number, and can be installed on a Linux OS.

c VM updates will install a new version of the package, if the version is incremented for new builds.

d Contents of the TAR file will be installed into the root directory of the resulting VM.

3 Package with complete metadata:

a Name the TAR file <anyname>.tar.gz or <anyname>.tgz

b A file named manifest.xml must be contained in the TAR, according to the following specification.

The manifest.xml file must conform to the following example:

<?xml version="1.0" encoding="UTF-8" standalone="no"?><package format="1.0" type="linux">

<name>packagename</name><version>1.0.0.0-build1</version><vendor>special apps</vendor><depends>package1, package2, package3</depends><arch>i386</arch><short-description>Best special app</short-description><description>A sample package – the best app!</description><preinstall>#!/bin/shecho "Hello from the preinstall"</preinstall><postinstall>#!/bin/shecho "Hello from the postinstall"</postinstall><preremove>#!/bin/shecho "Hello from the preremove"</preremove><postremove>#!/bin/shecho "Hello from the postremove"</postremove><configuration-files><file>/opt/myapp/config.xml</file></configuration-files>

</package>

Include all the XML attributes shown above, although values may be empty except for <name>, <version>, <vendor>, and <arch>. The value of <arch> can be “none”, “i386”, or “amd64”.

OS installation fails if a package marked as “i386” is installed on a 64‐bit OS, or if a package marked “amd64”

is installed on a 32‐bit OS. Packages marked as “none” install on any architecture.

The <short-description> is a one line description, while <description> is a multi‐line description.


60 VMware, Inc.

Section <configuration-files> may contain any number of configuration files in <file> elements. These

files must already exist in the TAR, and will be marked as Config files in the RPM and DEB package. If a file

is so listed, it is not replaced when the package is upgraded.

File permissions and owners are preserved from the contents of the TAR, however all users and groups must

exist on the VMware Studio appliance, otherwise file ownership defaults to root, group root.

Operating System Footprint ReductionYou can reduce the size of most virtual appliances by running the VMware Studio footprint reduction scripts.

Although these scripts do not affect application packages specifically, they run before and after application

installation. One script eliminates unused packages, while the other removes unnecessary files.

To reduce the size of a virtual appliance

1 In the VMs > Application tab, scroll down to Application Installation Customization.

2 Click Application Pre‐Install Script to display the script text, read the comment, and uncomment lines

(that is, erase #) starting with cut_pkgs_wrapper=run_cut_pkgs.sh.

This script runs before application installation to detect and eliminate unused packages.

3 Click Application Post‐Install Script to display the script text, read the comment, and uncomment lines

starting with cut_files_wrapper=run_cut_files.sh.

This script runs after application installation to remove unnecessary files.

4 Click Save and Build to preserve your uncommenting and rebuild.

Output diagnostics are saved under /opt/vmware/www/build/<buildID>/status in the cutpkgs.log and cutfiles.log files.

5 You can customize the script templates in /opt/vmware/etc/footprint if needed.

Just Enough Operating SystemThe term JeOS (Just enough Operating System) refers to altering an OS by removing unnecessary interfaces,

libraries, file, and executables if applications do not need them. JeOS‐style VMs have three key benefits:

Smaller server builds, for improved resource‐efficiency

Removal of vulnerable components, decreasing security risks

Fewer components to update, reducing management effort

VMware Studio contains two CLI commands to help create JeOS servers:

jeoser – performs static analysis on application packages to find just enough OS to run the application.

mkjeosvm – based on the analysis of jeoser, create a small virtual appliance (JeOS)

This is an experimental feature, so please be aware of the conditions listed in the EULA and on the Web page

https://www.vmware.com/support/policies/experimental.html. More details about this feature are posted as a

blog on the VMware Studio communities forum, and a video is available.

VMware, Inc. 61

6

This chapter explains the following topics:

“VMware Studio VAMI Service” on page 61

“Default Management Services” on page 62

“Creating a Management Service” on page 63

“Importing a Management Service” on page 64

“Customizing the Initialization Script” on page 65

VMware Studio contains several default management services, and it allows you to create new ones.

VMware Studio VAMI ServiceFigure 6‐1 shows the implementation framework of Virtual Appliance Management Infrastructure (VAMI)

services on top of CIM providers.

Figure 6-1. VAMI Services

VMware Studio‐built virtual machines carry an in‐guest management component, the Virtual Appliance

Management Infrastructure (VAMI). All management services provided by VAMI are implemented as

common information model (CIM) providers. VAMI services use the small footprint CIM broker (SFCB) as a

CIM object manager (CIMOM). CIM is a standard from Distributed Management Task Force (DMTF). The

VAMI services can be underpinned as tabs in the Web console.

Adding a Linux Management Service 6


62 VMware, Inc.

VAMI has the following components:

HTTP Server – A lightweight Web server using lighttpd to host the management Web console.

CIM Broker – The small footprint CIM broker (SFCB) acts as the management agent for the VM. CIM is

a standard from the Distributed Management Task Force (DMTF); see http://www.dmtf.org for details.

VAMI UI Framework – A container for the VAMI service Web interface; a tab in the Web console.

VAMI Services – VAMI services are used to expose a Web interface to manage the VM. A VAMI service

can contain a Web interface, the CIM provider, additional files, and Web server configuration. The Web

interface can optionally use a JavaScript API for better integration with the VAMI UI framework.

Authentication – The pluggable authentication module (PAM) is used to authenticate access to the

management Web console and CIM APIs. The authentication module creates a session file for each user,

which is stored at /opt/vmware/var/lib/vami/core/session as a file. The time‐out for sessions is

controlled by the environment variable VAMI_AUTHENTICATION_TIMEOUT and specified in number of

minutes. The default setting is one day (1440 minutes).

Restricted Access to VAMI CLI and VAMI User Interface – Studio now provides the option for ISVs to

control the access to VAMI user interface and VAMI CLI. On generated appliances only root users can

now access the VAMI interface and VAMI CLI. To provide access to VAMI interface and VAMI CLI for

other users, the administrator has to edit the build profile and set the vadk:vamiAdmin attribute.

Example 6-1.

<vadk:User vadk:username="vmit" vadk:password="dm13YXJl" vadk:passwordFormat="base64" vadk:fullname="VMwareIT" vadk:uid="" vadk:vamiAdmin="true"/>

As stated in “Virtual Appliance Management Infrastructure (VAMI)” on page 17, VMware Studio offers many

optional management components. The vadk:VAMISection_Type fields in the XML profile controls which

components get injected into the provisioned virtual appliance.

vadk:LoginTTY – The blue‐screen server console.

vadk:ShowEULA – EULA appearing on the virtual machine console.

vadk:ManagementSrv – Web services back‐end (CIM object manager).

vadk:ManagementGui – Web user interface and HTTP server, which depends on the back‐end.

vadk:RunBootScripts – Boot scripts.

vadk:VMToolsCore and vadk:VMToolsX – VMware Tools, as presented by the virtualization platform.

vadk:UpdateSection_Type – The update service.

vadk:InitScript – Customizable service initialization script run each time the virtual appliance boots.

See “Customizing the Initialization Script” on page 65.

Default Management ServicesVMware Studio comes with a default set of management services that can be included with any Linux‐based

virtual machine. When you log into the VMware Studio Web console and click the Library > Linux tabs, this

list appears showing the default management services:

core – The VAMI framework and Web container to hold other services.

system – Displays basic system information, and has an interface to shutdown or reboot the VM.

network – Allows end‐users to configure their network and proxy settings.

update – If you are planning to ship a virtual appliance, VMware recommends that you include this

service as part of your build profile. Update service simplifies the maintenance of virtual appliances by

applying updates from a ISV‐managed update repository, and integrates with Update Manager to allow

centralized management through vSphere (see http://www.vmware.com/support/pubs/vum_pubs.html).

http://www.dmtf.org

http://www.vmware.com/support/pubs/vum_pubs.html

VMware, Inc. 63

Chapter 6 Adding a Linux Management Service

VAMI packages may also include appliance‐config, init, and servicebase.

Management Services with Eclipse

VMware Studio provides an Eclipse plugin for packaging your management service. For more information,

see Chapter 8, “Using the VMware Studio Plugin for Eclipse,” on page 75, especially “Creating Management

Services” on page 77.

Creating a Management ServiceVMware Studio lets you add your own management services in the virtual machine, with their Web interface

appearing as tabs in the Web console of the generated virtual machine. These management services are

packaged in a tar or tar.gz file and imported into VMware Studio.

You can package management services using the VMware Studio Plugin for Eclipse (see “Management

Services with Eclipse” on page 63) or create them manually as described in this section. Management services

can be made part of your Linux‐based virtual machine by specifying them in the build profile.

When you create a management service, the service must be encapsulated in a tar or tar.gz file with the

following directory structure:

service.xml – Contains service name, version number, and description of the management service.

Installed in the /opt/vmware/var/lib/vami/${servicename}/ directory.

conf/lighttpd.conf – Configuration settings for the lighttpd service. Settings are appended to the original lighttpd.conf file and installed in /opt/vmware/var/lib/vami/${servicename}/conf.

provider/*.reg – CIM provider registration files. At build time, VMware Studio installs this file into the

/opt/vmware/var/lib/sfcb/stage/regs/ directory.

provider/*.mof – CIM provider managed object format (MOF) files. Installed into the

/opt/vmware/var/lib/sfcb/stage/mofs/root/cimv2 directory.

provider/*.so – CIM provider shared libraries. Installed into /opt/vmware/lib.

system-root/* – Content of the service that must reside in (get copied to) the system root directory of

the VM’s operating system.

view/view.xml – Describes the tab title to show in the Web console, contains information about the tabʹs

content. Installed in the /opt/vmware/share/htdocs/service/${servicename}/ directory.

view/* – All view‐specific files for this service. Contains HTML, JavaScript, and images. Installed in the

/opt/vmware/share/htdocs/service/${servicename}/ directory.

web-root/* – The view directory contains service‐specific Web user interface files. Additional files that

must be placed at the Web root level of lighttpd. Installed in /opt/vmware/share/htdocs.

Of the above files, only service.xml is mandatory, and view.xml is needed for its associated user interface.

service.xml

This file describes the identity and dependencies of the service. The following code block describes the

service.xml format:

<service><name>ServiceName</name><version>1.0.0.0</version><description>This provides the build service to create new appliance</description><requires>

<packages>rpm_or_dep_package_dependencies separated by commas</packages><services>other_service_dependencies separated by commas</services>

</requires></service>


64 VMware, Inc.

view.xml

This file describes the Web interface properties, including the tab title and contents of the tab. Content can be

of two types, url or html. When content type is url, it is the location of the file that appears in the UI tab.

The following code block describes the view.xml format when content type is url:

<service><title>ServiceTitle</title><content type="url" url="index.html"/>

</service>

If the URL is prefixed with a slash (for example /index.html), the URL location is relative to the document

root of the Web server, /opt/vmware/share/htdocs. Otherwise the URL location is relative to where the

service views are installed, /opt/vmware/share/htdocs/service/${servicename}.

The following code block describes the view.xml format when content type is html:

<service><title>ServiceTitle</title><Content type="html">

<![CDATA[Hello world or other important html content]]>

</Content></service>

See “Management Services Web API” on page 113, for extended JavaScript API support with basic navigation,

communication, authentication and logging.

Creating a Vanilla VM

To disable all the optional VAMI services, or a subset of management services, change these elements in the

XML profile’s vadk:VAMISection_Type to false:

<vadk:ShowEULA>false</vadk:ShowEULA><vadk:SetHostname>false</vadk:SetHostname><vadk:SetNetwork>false</vadk:SetNetwork><vadk:CreateSSHKeys>false</vadk:CreateSSHKeys><vadk:RunBootScripts>false</vadk:RunBootScripts><vadk:LoginTTY>false</vadk:LoginTTY><vadk:ManagementSrv>false</vadk:ManagementSrv><vadk:ManagementGUI>false</vadk:ManagementGUI><vadk:VMToolsCore vadk:install="false" …/><vadk:VMToolsX vadk:install="false" …/>

The Web console interface is able to change some, but not all, of these settings. For more information on these

settings, see “Structure of vApp XML Build Profiles” on page 141.

Underlying CLI

You can run the vamimanager command to install, uninstall, extract, register, and unregister services. The user

interface uses the vamimanager command to implement actions.

Type vamimanager at the command line for information about its options.

Importing a Management ServiceYou can include any of the existing VAMI services into your build profile. You can also include a management

service that you have created in a newly built VM.

To import a management service

1 Log into the VMware Studio Web console and click the Library > Linux tabs.

2 Click the Import Service button. Browse to the location of the tar or tar.gz file that you created for your management service. Click Import Service.

VMware, Inc. 65

Chapter 6 Adding a Linux Management Service

3 If correctly created, your new service appears in the list, with its version and description. VMware Studio

maintains the management services repository under /opt/vmware/var/lib/build/services.

4 Follow instructions for creating a new VM, or for editing an existing VM.

5 On the Management page under Management Services, click the Add button, select the new service from

a list, and click Add.

6 Optionally, click Customize GUI Tab Order, which allows you to adjust the order of the tabs.

7 Save and build the VM.

This service is installed as RPM or DEB package in the resulting VM and appears as a tab (if it contains a UI

component) in the VM management Web console.

Customizing the Initialization ScriptThe VMware Studio initialization script vaos_init.sh integrates into the Linux /etc/init.d mechanism of

service initialization scripts. It runs each time the virtual appliance reboots.

You can customize the initialization script, the name of which is specified in the vadk:InitScript field of the XML profile’s vadk:VAMISection_Type. The main reason for customizing the script is to avoid critical errors

during and after virtual appliance reboot.

To customize the vaos_init.sh script

1 Find the initialization script in /opt/vmware/etc/vaos/vaos_init.sh and copy it to a new file, for example vaos_myinit.sh in the same directory.

2 Edit the new script you just created with your changes.

3 Find the XML profile in /opt/vmware/var/lib/build/profiles and change the following line to say

for example vaos_myinit.sh instead of vaos_init.sh.

<vadk:InitScript vadk:template="/opt/vmware/etc/vaos/vaos_init.sh"/>

4 Launch a new build and test your changes.

The vaos service starts in 19th position at run levels two and zero, as you can see in /etc/rc2.d.


66 VMware, Inc.

VMware, Inc. 67

7

If you are an ISV shipping a virtual appliance, VMware highly recommends creating an Update Repository for

your virtual appliance. This enables you to remotely update virtual appliances deployed at customer sites.

This chapter describes how to publish updates to your virtual appliance and includes the following topics:

“Overview of Updates” on page 67

“Generating an Update” on page 68

“Publishing an Update” on page 71

“Testing Against a Staging Update Repository” on page 72

“Diagnosing Failed Updates” on page 73

“Update Repository XML” on page 73

“Supporting Central Updates with VMware vCenter Update Manager” on page 74

Overview of UpdatesAfter a virtual appliance is built and released, you might need to publish an update for it. VMware Studio

defines an update as a set of RPM or DEB packages. The VMware Studio update repository contains these

packages and a manifest file that describes the contents of a particular version of the virtual appliance. In the

virtual appliance model, the ISV creates and publishes updates to the repository.

A virtual appliance deployed at a customer site can “phone home” to an update repository to retrieve updates,

which might include:

Operating System updates – You can download OS updates from the OS provider’s Web site.

Application updates – You can provide your own application updates.

To update a virtual appliance

1 Build your first virtual appliance so it can receive updates from an update repository hosted at an ISV site.

In VMware Studio (see “Management Tab” on page 46) enable the update service before a build. When

you enable updates for a VM, VMware Studio creates an update repository after the VM build.

2 After the appliance is shipped, monitor updates for its OS in addition to the application stack components

that are present in your virtual appliance.

3 Analyze the changes and select applicable updates for your virtual appliance.

4 Generate the update in the form that your virtual appliance understands. For generating updates using

VMware Studio, see “Generating an Update” on page 68.

5 Test the updates to make sure that your application continues to work as before in the virtual appliance.

6 Publish the update. See “Publishing an Update” on page 71. You have a choice of several publication

methods, as summarized in “Testing Against a Staging Update Repository” on page 72.

Managing a Linux Update Repository 7


68 VMware, Inc.

Figure 7‐1 shows VMware Studio creating an update repository for a virtual appliance VM on a staging server.

The ISV also has the option of exporting the update repository as a ZIP file or as an ISO image for distribution.

Figure 7-1. VMware Studio Update Repository

Figure 7‐2 shows the different channels where a virtual appliance VM can retrieve updates. Both the ZIP file

and ISO image contain the complete update repository that the ISV builds. The ZIP can be deployed to a local

Web server within the customer’s local area network, whereas the ISO can provide off‐network updates if the

VM is configured with a CD drive.

Figure 7-2. Virtual Appliance Update Retrieval

Generating an UpdateFigure shows the flow of creating a virtual appliance and its update repository. When the update management

service for a VM is enabled, an update repository is created at the end of the VM build. An update repository

cannot be created without building the VM.

Figure 7-3. Update Flow During VM Builds

During a VMware Studio update build, the port 7 open requirement (“Prerequisites” on page 21) applies to

the host of the Update Repository, in other words the repository server or staging server.

Start EndBuild VMor vApp

CreateUpdate?

Build Update Repository

no

yes

VMware, Inc. 69

Chapter 7 Managing a Linux Update Repository

To generate an update from the VMware Studio Web console

1 Log into the VMware Studio Web console.

2 In the VM List, select the virtual appliance for which you want to generate an update.

3 Under Actions, click Edit Profile.

4 In the Description tab, change the version number in the profile for the VM. This is the key indicator that

an update was generated for an existing virtual appliance. The Version is a number in N.N.N.N format,

where N must be a number between 0 and 65535.

5 In the Management tab, click Add and enable the update service. A new Update Service section appears

on the page, with a section for Update Service Repository Settings.

6 Choose and type a Repository URL to establish an update site for your virtual appliances in the field.

The Repository URL should be on a publicly accessible Web site.

On the VMs > Management page under Update Service settings, you can change the Repository URL.

When a virtual appliance updates, it gets the changed Repository URL, so the following time it checks for

an update, it will look in the new location. Reboot is not required. To enable this feature, the old repository

must contain a final update with the new repository location, and the new repository must contain an

initial update. The final update and the initial update may be the same appliance version, or different.

7 Provide an Update Description so the end‐user knows what this update contains. The VendorUUID and

ProductRID are mandatory for use with VMware vCenter Update Manager.

8 Complete the details for Repository Server Settings, where the update archive gets copied after a build.

If you plan to copy the update from a staging server to the update repository on an external production

Web site, make sure the Repository URL points to that external production Web site, not to the internal

staging server. After the build completes, copy the entire staging server update to the external production

Web site. To ease the task of copying all the update files, under Repository Export Settings you can click

Update Archive and specify a ZIP Filename.

VMware Studio creates a new manifest with the new version number specified in the build profile, and

updates the repository. VMware Studio marks the new version of the virtual appliance as the latest version

and copies the new and changed packages to the update repository. If you remove a package from the build

profile, the newly generated manifest reflects this removal. The VAMI agent does not delete packages when

updating an appliance, but you can add a preupdate or postupdate script to remove packages.

Updates on CDROM

If you are building an appliance that lacks external network access, or if your customers prefer, you can deliver

updates on CDROM.

To generate an update from the VMware Studio Web console

1 Follow the general procedure for “Generating an Update” on page 68.

2 In Step 6, select CDROM updates instead of Specify repository.

Fields for Repository URL, Username, and Password become dimmed out.

3 Under Repository Export Settings, click ISO Archive and specify the ISO Filename to create.

4 After the build succeeds, the update is copied to the File Transfer Path on the File Transfer Hostname.

5 Burn the ISO Filename to CDROM for delivery to your customers.

Alternately, you can make the ISO image available at a location on your production repository Web server,

and let customers download it and burn the CDROM themselves.

NOTE Changing the virtual appliance name, VendorUUID, or ProductRID in the build profile while

generating updates might affect integration with VMware vCenter Update Manager. See “Supporting

Central Updates with VMware vCenter Update Manager” on page 74 for more information.


70 VMware, Inc.

Updates Requiring Reboot

Your application might require a system reboot after applying an update. If an update causes the appliance to

reboot, you should warn end‐users about this the Update Description field. If you want your virtual appliance

to reboot after an update, you can run the following command as part of the update:

/usr/share/update-notifier/notify-reboot-required

This creates the file /var/run/reboot-required, which is deleted after reboot. This command should go in

the update manifest’s postInstallShellScript (not the same as the Application Post‐Install Script). To put

it there, edit the VM profile in /opt/vmware/var/lib/build/profiles, find vadk:UpdateSection_Type, and add the notify-reboot-required line before final status checking.

Digitally Signing an Update

When you sign an update, the end user is able to authenticate it as being from a valid source.

With Studio 2.1 and later you can sign updates by using one public key, which remains in effect for the lifetime

of a virtual appliance. Signing is done by a script, encapsulated in the XML profile, that runs after you generate

the update manifest. You can find virtual appliance profiles in the /opt/vmware/var/lib/build/profiles directory. In an XML profile, look in the vadk:UpdateSection_Type under vadk:DigitalSignature for the “pubkey” script, which calls the openssl rsa command to create a digital signature from a PEM key, placing

the results in the specified signature file.

Before update begins, another script validates the signature file and public key. Look for the “validate” script underneath the “pubkey” script. Update proceeds only if the signature validates. In the update repository, the file manifest-latest.xml.sig contains the digital signature.

If you are using self‐signed certificates from openssl, the best practice is to use an agreed‐upon public key to sign all virtual appliance and update repositories.

To support custom digital signing, you could modify these scripts to use your existing signing infrastructure,

instead of using openssl.

Digital signing involves two stages. The sign_manifest script takes a file as input, and outputs a signature. In official mode, the script uses official signing infrastructure to perform the signing, which is useful for

production. In testing mode, the script calls openssl with a private key stored in publicly available location

to do the signing. That is useful for development builds.

The second stage is the get_public_key script, which outputs the public key. Similarly it has an official mode

and a testing mode. The produced public key is embedded into a virtual appliance, which is later used to

validate the upgrade manifest file. The validation process is always done using openssl.

Adding Your EULA to an Update

With Studio 2.1 and later you can include a new or revised EULA with an update. The vamicli command,

when run with the --acceptula option, creates an update that auto‐accepts any EULA that exists, instead of explicitly asking the user to accept the EULA.

vamicli update --install <version> --accepteula

By editing the XML profile, you can set the EULA display policy to always, checkversion, or never. The checkversion policy shows the EULA only if the update version is newer than the introducedVersion.

NOTE If you generate an update using a different version of VMware Studio than used to build the original

virtual appliance, the new VMware Studio creates a new key and signs the repository with it, so the update

fails to validate and will not install. The workaround is to extract the public key on the new VMware Studio

by running this openssl command:

openssl rsa -in /opt/vmware/etc/update.pem -pubout -out signature.key

Install the output signature.key file as /opt/vmware/var/lib/vami/update/data/signature.key on the original virtual appliance, then apply the update, which should validate and install.

VMware, Inc. 71


Unlike the EULA mechanism for initial virtual appliance install, the update EULA does not currently support

multiple locales.

The user can enable the update service from the Management tab, and then edit the profile to add a EULAList element after the vadk:DigitalSignature in the vadk:UpdateSection_Type. In this EULAList element,

you can specify the policies, for example:

<Section xsi:type=”vadk:UpdateSection_Type”>...<vadk:DigitalSignature>...</vadk:DigitalSignature><vadk:EULAList vadk:displayPolicy=”always” vadk:introducedVersion=”1.2.3.4”>

<vadk:EULA>This is an update EULA

</vadk:EULA></vadk:EULAList>...

</Section>

Publishing an UpdateAfter the fields are modified in the build profile, click Save and Build to build your virtual appliance with the

updates. As part of the build process, the update repository is updated with a new manifest. You can see that

manifest-latest.xml is updated to reflect the update, and additional packages are copied to the repository.

Test the generated virtual appliance to ensure it works as expected with the updates. Once you are ready to

make the updates visible to end‐users, you can copy the entire contents to your external Web server that hosts

the update repository. Because deployed virtual appliances at customer sites have the URL of this Web server

embedded, the following actions can occur:

Virtual appliances flag an update‐available, if automatic check for update is enabled.

The end‐user can manually check for updates to view available updates.

The end‐user can see the Update Description and react to any critical information it contains. For example,

you can include this advisory message: “This virtual appliance will reboot after applying this update.”

Publishing an Update Repository from ZIP

The repository information that you configure in the Web console persists in the build profile. Additionally,

VMware Studio can create a ZIP archive of each update when you enable Update Archive Export.

You can use Update Archive Export to control publishing of updates by manually copying the archive and

extracting the update files to a remote Web server. During the build, VMware Studio creates the following

update ZIP file:

/opt/vmware/www/build/<buildNumber>/exports/zip/<exportFile>.zip

To publish an update from the ZIP archive created using Repository Export, extract the contents of the file in

the document root of the URL that was specified as the update URL. For example, if you set the update URL

to http://<your-server>/updates/ and set the document root in the Web server to /var/www/htdocs/, then you would extract the contents of the ZIP file into /var/www/htdocs/updates/ on <your-server>. Virtual appliance end‐users could now retrieve and install the update from your Web server.

The following example is for Linux‐based Web servers.

NOTE It is not possible to publish updates for a vApp in a single unit. The ISV must create a separate update

repository for each constituent VM in the vApp.

CAUTION During the time when you are publishing an update into a previously existing updates directory,

users downloading the update might encounter data corruption. A best practice for Web sites is to publish your

update first on a staging server, and later sync it to the production server during off hours. Another solution

is to copy the new update repository to a new directory, and rename the directory when the upload is complete.


72 VMware, Inc.

To publish an update from the ZIP archive

1 Connect with SSH to your production update server, in this example support.example.com:

ssh support.example.com

2 Run scp to secure copy from the VMware Studio virtual appliance <vmwStudio> into /tmp:

scp root@<vmwStudio>:/opt/vmware/www/build/<buildNumber>/exports/zip/<exportFile>.zip /tmp

If the production update server has HTTP access to your virtual appliance, you could instead run:

cd /tmp; wget --no-proxy http://<vmwStudio>/build/<buildNumber>/exports/zip/<exportFile>.zip

If your network does have a proxy, wget takes it from the http_proxy environment variable.

3 Create a directory for updates on your Web server:

mkdir -p /var/www/htdocs/updates/productXYZcd /var/www/htdocs/updates/productXYZ

The path you specify must be in the Web server document root (in this example, /var/www/htdocs) and must correspond to the repository URL specified for the appliance during the build.

4 If this directory contains files from a previous update archive, the previous update manifest XML file,

manifest-latest.xml, should be renamed as a backup file. The name of this backup file is arbitrary. For

example, you can embed its creation date in the format yyyymmdd for year, month, and date. To make your

backup of the old update manifest file, run a command like the following. If you ever need to revert your

update server to an older update version, you can overwrite the manifest-latest.xml file with the

contents of a previous manifest backup file.

mv ./manifest/manifest-latest.xml ./manifest/manifest-<yyyymmdd>.xml

5 Run the following commands to extract the update archive contents into the productXYZ directory:

unzip /tmp/<exportFile>.zip

Testing Against a Staging Update RepositoryWhen building a virtual appliance, it is not a requirement to publish updates from a ZIP archive. That is only

one mechanism. In this example, the Update Repository URL in the build profile points to a HTTP or HTTPS

location on the production server, while the update File Transfer Hostname and File Transfer Path point to a

directory on the staging server. This setup is shown in Figure 7‐1.

As an ISV you have three ways to deliver updates:

From a Web server on the public Internet, called Production Server in the Figure 7‐1 diagram. In the VM

build profile, Update Repository URL refers to the update location on this Web server.

By delivering a ZIP file to your customers, who unzip the revised software into the update repository on

their local Web server, and set their virtual appliance to update from the URL of the update repository on

this local Web server. The middle of Figure 7‐2 shows this delivery mechanism.

By delivering a CDROM to your customers, who place the disc in a CD drive accessible to the appliance

and enable update from CDROM. The bottom of Figure 7‐2 shows this delivery mechanism.

With the staging server setup, here is how you can test updates against the staging (not production) repository

from your virtual appliances. Doing so avoids manual installation of any RPM or DEB update packages.

Open a terminal to the appliance of interest and follow these steps:

1 Edit /opt/vmware/var/lib/vami/update/provider/provider-deploy.xml and change repositoryAddress, replacing the URL pointing to the update repository on the production server with

the URL of update repository on the staging server. Obviously this is only for internal testing.

2 Run this command to restart the CIM broker:

/etc/init.d/vami-sfcb restart

VMware, Inc. 73


3 Run this command to check for update availability:

/opt/vmware/bin/vamicli update --check

4 Run this command to install the update.

/opt/vmware/bin/vamicli update --install latest

5 Run the desired tests to verify that the expected updates occurred in the appliance.

Checking for updates requires the HTTP 1.1 protocol on your update repository Web server.

Diagnosing Failed UpdatesStudio 2.1 and later provide the vamisupport script, which bundles up log files into a tar file (tarball) for diagnosis. You can find this script at /opt/vmware/bin/vamisupport on all Studio generated appliances. The tarball is useful for general troubleshooting, because it captures more than just update related information.

After a virtual appliance update error, support personnel can ask the customer to run the vamisupport script. The script reports where it has written the collected log files. The customer can then scp the resulting tarball to a computer with email service, and transmit it to support personnel for diagnosis. In addition to other data,

the vamisupport script saves these files, which might be useful to diagnose virtual appliance update errors:

/opt/vmware/var/log/vami/vami.log

/opt/vmware/var/log/vami/updatecli.log

/opt/vmware/var/lib/vami/update/data/job/<job-id>/*

The job/<job-id> directory contains a copy of the manifest files, pre‐install scripts, post‐install scripts, and

other scripts that are related to a particular update job. If you see multiple <job-id> directories, check their modification times for the most recent.

Update Repository XMLThe update repository has a specific format. Each time you publish an update to the update repository, new

packages (and new versions of existing packages) are added to the repository. The old manifest is moved to

manifest-<version>.xml, the new manifest-latest.xml replaces the old one. Also manifestrepo.xml is updated to reflect any new packages in the repository. Examine the manifest-latest.xml file to verify that your update was published to the repository. The manifest-latest.xml structure is the following:

<update><version> ...<description> ...<vendorUUID> ...<productRID> ...<product> ...<vendorURL> ...<fullVersion> ...<postInstallScript> ...<preInstallScript> ...<vendor> ...<UpdateInfoList> ...<productURL> ...<supportURL> ...<releaseDate> ...<PackageGroups>

<group installOrder=0> ...<package name= ... ></package>...

</group></PackageGroups>

</update>

The XML contains update metadata including introduced-version for VMware vCenter Update Manager

(VUM) to match. Look for the UpdateInfo section, which you can edit to support Update Manager.


74 VMware, Inc.

<vadk:UpdateInfoList><vadk:UpdateInfo vadk:introduced-version="1.0" vadk:category="feature"

vadk:severity="important" vadk:affected-versions="" vadk:description=""vadk:reference-type="vendor" vadk:reference-id="" vadk:reference-url=""/>

</vadk:UpdateInfoList>

You can edit the XML section ExtendedConfigList, which gets placed into the manifest file.

<vadk:ExtendedConfigList>< [edit this section] />

</vadk:ExtendedConfigList>

The XML profile can enable and disable digital signatures. See “Digitally Signing an Update” on page 70.

Supporting Central Updates with VMware vCenter Update ManagerThe updates that are published for an appliance can be applied by the end‐user either using the Web console

of the virtual appliance or using the centralized update management provided by Update Manager.

VMware vCenter Update Manager allows system administrators to create a baseline that controls updates to

all virtual appliances, or a baseline for a particular appliance, or a baseline for appliances from a given vendor,

and so forth.

Any baselines specified using the vendor name or product names are internally referenced with the

VendorUUID and the ProductRID fields. Update Manager can retrieve the VendorUUID and ProductRID

from virtual appliances.

VendorUUID – The globally unique identifier for your company or organization. The UUID can be a

Windows GUID (Globally Unique Identifier).

ProductRID – Unique product identifier, which should be unique across all appliances from a vendor.

The VendorUUID and ProductRID fields are mandatory in build profiles with the update repository enabled.

Update Manager requires the VendorUUID and ProductRID while referencing the appliances in the baselines.

If the vendor name or appliance name were to change for a future version of a virtual appliance, then any

baselines created by the user would become invalid.

To avoid invalid baselines, VMware requires that developers enter their VendorUUID and ProductRID when

creating update repository information.

VMware, Inc. 75

8

The VMware Studio Plugin for Eclipse can help you package applications and develop Linux‐based virtual

appliances and vApps. This chapter contains the following sections:

“Requirements of VMware Studio Plugin for Eclipse” on page 75

“Getting Started with VMware Studio Plugin for Eclipse” on page 75

“Packaging Applications to Run In a Virtual Machine” on page 76

“Creating Management Services” on page 77

“Additional Eclipse Features” on page 77

Using the VMware Studio Plugin for Eclipse, you can control the user interface portions of VMware Studio

like an application under development. The VMware Studio Plugin for Eclipse is also useful for packaging

Linux‐based applications. The VMware Studio Plugin for Eclipse is also useful for making your own

management services, which create new tabs in the Studio Web console. See Chapter 6, “Adding a Linux

Management Service,” on page 61 for more information about management services.

Requirements of VMware Studio Plugin for EclipseThe VMware Studio Plugin for Eclipse has the following prerequisites.

VMware Studio already installed.

Eclipse 3.4 (Ganymede), 3.5 (Galileo), or 3.6 (Helios). Visit the http://www.eclipse.org/downloads Web site

to download and install. The Java IDE and Apache Ant 1.7 are included in Eclipse releases.

On all Eclipse platforms (Linux, Mac, Windows) check for either of the following:

Access to the VMware Studio for Eclipse installation site, http://<StudioIPaddr>/eclipse/update/

The VMwareStudioForEclipse-<version-num>.zip package that you can download to local disk

from the VMware.com web site.

Getting Started with VMware Studio Plugin for EclipseThe VMware Studio Plugin for Eclipse must be installed into the Eclipse framework.

To get started with VMware Studio Plugin for Eclipse

1 If you are running Eclipse behind a firewall, set the proxy in Eclipse. This is because Eclipse uses the HTTP

proxy when looking at dependencies for the VMware Studio plugin during installation.

a Select Window > Preferences > General > Network Connections > Manual proxy configuration, or

use the system proxy configuration if available.

b Set the HTTP proxy for Eclipse and possibly the SSL proxy.

Using the VMware Studio Plugin for Eclipse 8


76 VMware, Inc.

2 Install the plugin from the VMware Studio IP address or ZIP package.

a In Eclipse 3.4, select Help > Software Updates > Available Software > Add Site.

In Eclipse 3.5, select Help > Install New Software > Add.

b For Location, do one of the following:

In the text box type http://<StudioIPaddr>/eclipse/update, URL of the VMware Studio

for Eclipse installation site, and click OK.

Click Archive, browse to find, and open the VMwareStudioForEclipse-<version-num>.zip package that you previously downloaded to local disk.

c Select the VMware Studio Plugin for Eclipse check box.

d In Eclipse 3.4, click Install. In Eclipse 3.5, click Next.

3 Restart Eclipse when prompted.

4 Select Window > Show View > Other > VMware Studio > VMware Studio Explorer.

This adds a view of VMware Studio into an existing perspective.

5 In the VMware Studio Explorer tab, double‐click the bar where it says to configure VMware Studio.

6 In the VMware Studio Connection dialog box, specify the host name or IP address of the VMware Studio

appliance, port 5480, user name root, and the password you set. Click Finish.

7 Under the VMware Studio Explorer tab, double‐click VMware Studio Web Console. The Web Console

view appears. You can add profiles and resources using the Explorer view. The VMware Studio Explorer

view includes:

VMware Studio Web console – You double‐click this line to open the VMware Studio user interface

in an embedded Web browser. You probably will be asked to ignore or accept a security certificate.

VM Profiles – Shows the VMs you have created, with profile and sequence of builds.

vApp Profiles – Shows the vApps you have created, with profile and sequence of builds.

Resources – Includes operating system images and package repositories.

Packaging Applications to Run In a Virtual MachineYou can use VMware Studio Plugin for Eclipse to package software for inclusion in a Linux‐based VM.

To create a new Linux package

1 From the File menu, select New > Other > VMware Studio > VMware Studio Linux Package, click Next,

possibly change the Add to Project setting, and click Finish.

The new Linux package appears as a VMware Studio Package (VSP) file in under the project you chose.

2 Add files to your package by importing them as files or importing an entire directory. You can set the

metadata such as package name, version, and so forth. You can also modify the pre‐install, post‐install,

pre‐remove, and post‐remove scripts.

3 When you open a VSP file in Eclipse, an editing window appears with “Package configuration data” title.

At the top right of this editor, click the Build Package button. In the dialog that appears, select a package

Repository name, a output filename, and optionally a VM profile to which this package should be added.

If you select a VM profile, you can click the check box to automatically start a VM build when the package

upload finishes.

When you create a package, the files tab (bottom of window) allows you to import files and select the

destination in the appliance to install each of them individually. You can mark a file as a configuration file

by right clicking on a file and selecting Mark as Config. You can also import a directory. When a directory

has its source location specified, during the package export, that source location is added into the package

recursively, using default file attributes. If a directory has no source location specified, then the directory

is created on the appliance but no files are copied.

VMware, Inc. 77

Chapter 8 Using the VMware Studio Plugin for Eclipse

Creating Management ServicesYou can add your own management services and create new tabs in the Web console of your virtual appliance.

See Chapter 6, “Adding a Linux Management Service,” on page 61 for more information about the structure of

management services.

The VMware Studio Plugin for Eclipse provides the concept of a “project” to help you develop and build

management services. The normal development cycle is to develop your application, add new files into the

structure of a service project, then use the build.xml script to create a tar.gz file for the service.

To create a new Service with Eclipse

1 From the File menu, select New > Project > VMware Studio > VMware Studio Service Project, click Next,

type a project name, possibly change the service name and other attributes, and click Finish.

A new service.xml tab appears with the attributes you just set. For full details about the service directory

hierarchy, see “Creating a Management Service” on page 63.

2 To package the service as a tar.gz file, run build.xml as an Ant script. You can do this by right‐clicking build.xml under your project and selecting Run As > Ant Build.

The Ant build log appears in the Console, showing the name of the tar.gz file if successful.

You can predefine the build.xml Ant script to build your service, and where to put the tar.gz file.

To import your newly created service into VMware Studio, see “Importing a Management Service” on page 64.

Additional Eclipse FeaturesYou can upload a CD image by right clicking in the VMware Studio Explorer tab, selecting Upload ISO Image,

and opening an ISO file. You can also delete or rename ISO files.

You can manage package repositories (by creating, deleting, and renaming them). You must create a package

repository before you can export a Linux Application Package.

Within package repositories, you can delete and rename VSP package files.

You can add package repositories to a VM profile. In the VMware Studio Explorer tab, expand VM Profiles,

expand a VM, right‐click its profile, and select Add package repository. This downloads the profile from the

VM, adds a package repository into the application packages of the VM, and saves the profile back to the VM.

Be careful: if someone else is editing the same profile at the same time, your profile changes might be

overwritten, or overwrite the other person’s changes.

You can start and monitor builds of a VM or vApp by right clicking on a specific Profile Summary and

selecting Start New Build. All the builds are listed with their status. You can cancel a build that is currently

running by right clicking on it and selecting Cancel Build, or delete a build by right clicking on it and

selectingDelete.

You can access the Logs and Exports of each build by double clicking on them inside the VMware Studio

Explorer tab. You can open the Eclipse XML editor and read the profile.xml that was used for each build by

double clicking on the profile. The Eclipse XML editor is read‐only.

You can open a VM or vApp Profiles in the VMware Studio Web console by double clicking on it.

A Linux application package is uploaded (exported) to the VMware Studio appliance as a compressed TAR

file, converted to a RPM or DEB package during the VM build, installed into the virtual appliance, and then

installed into the update repository.

You must manually increment the version of an application package if you want it to replace the old package

during an appliance update.

Welcome page describes how to get started with the VMware Studio plugin for Eclipse.

Live build logs provide message updates in real time, without you having to reopen the log file.

You can right‐click the Properties menu for exportable URLs of OVF, OVA, and ZIP distribution files.


78 VMware, Inc.

Usability improvements:

The VM tree representation becomes grayed out when the connection to it fails.

In the tree view, multiple select is supported for deleting.

Also you can delete by pressing keyboard Delete key.

Support for ant targets outside the Eclipse framework.

After you create a VM and application as a VMware Studio Package (VSP), the development environment

remains intact so the next build can follow the same pattern with less developer intervention.

Uninstalling the Eclipse Plugin

You can uninstall the VMware Studio Eclipse plugin.

To uninstall the Eclipse plugin

1 Do one of the following:

In Eclipse 3.4, select Help > Software Updates > Installed Software.

In Eclipse 3.5, select Help > About Eclipse > Installation Details > Installed Software.

2 Select VMware Studio Plugin for Eclipse and click Uninstall.

3 Restart Eclipse when prompted.

VMware, Inc. 79

Developing a Windows-Based VM


80 VMware, Inc.

VMware, Inc. 81

9

This chapter describes how to create a Windows‐based VM using the VMware Studio Web console.


“Operating System ISO Image” on page 82

“Adding Support for a New Windows OS” on page 83

“Windows Application Packages” on page 83

“Creating a VM Build Profile” on page 83

“Additional Fields for Windows Reference” on page 84

“Building a VM from the Build Profile” on page 87

“Testing the Generated VM” on page 87

“Reiterating the Build Process” on page 88

“Provisioning a Windows ISO in vSphere Datastore” on page 88

OverviewVMware Studio supports the creation of virtual machines containing a Windows‐based Server operating

system and user‐provided applications. Windows‐based VMs built by VMware Studio do not contain the

Virtual Appliance Management Infrastructure (VAMI) agent.

Prerequisites – OS and Application

This chapter assumes that you have downloaded the VMware Studio software onto a supported virtualization

product platform, as described in “Deploying VMware Studio” on page 22. You also need:

An ISO image from the list of Windows operating systems in “Operating System ISO Image” on page 82.

Sufficient space on the provisioning host’s datastore to store the ISO image. Windows Server 2003 requires

up to 622GB. Windows Server 2008 requires up to 3023GB. To speed up subsequent builds, on first build

VMware Studio copies the Windows ISO image into the datastore’s /iso subdirectory.

A valid license key for the Windows operating system you select. However with Windows Server 2008, if

you do not provide a license key, it defaults to the built‐in evaluation license key.

Your application shared on a Microsoft Network Folder, or packaged as a VMware Studio Package (VSP)

for Windows, as outlined in “Windows Application Packages” on page 83.

Accessing the Web Console

To access the Web console with your browser, navigate to the IP address of the VMware Studio appliance. The

access URL appears at install time, as described in “Deploying VMware Studio” on page 22.

Creating a Windows-Based VM 9


82 VMware, Inc.

Operating System ISO ImageTable 9‐1 lists the Windows distributions that VMware Studio supports.

OS Image Installation Options for Windows

Windows unattended installation requires a legitimate operating system image name for the given Windows

ISO image. The OSImage field in the build profile (same as OS Image in the Studio Web console) is where you

should enter the image name. Here are some possible options for Windows Server 2008 R2, specifically the

en_windows_server_2008_r2_standard_enterprise_datacenter_and_web_with_sp1_x64_*.iso image:

Windows Server 2008 R2 SERVERDATACENTER

Windows Server 2008 R2 SERVERDATACENTERCORE

Windows Server 2008 R2 SERVERENTERPRISE

Windows Server 2008 R2 SERVERENTERPRISECORE

Windows Server 2008 R2 SERVERSTANDARD

Windows Server 2008 R2 SERVERSTANDARDCORE

Windows Server 2008 R2 SERVERWEB

Windows Server 2008 R2 SERVERWEBCORE

You can see these options names in the Windows ISO, after VMware Studio mounts it under /mnt for a build, in the sources/ folder, as individual install_<image>.clg files.

For Windows Server 2003 R2 (specifically the en_win_srv_2003_r2_standard_with_sp2_cd1_*.iso image) the

following image option is available:

Windows 2003 Standard

Other editions of Windows Server 2003 R2 provide the following alternate image options:

Windows 2003 Datacenter

Windows 2003 Enterprise

Windows 2003 Web

NOTE For more information about the operating system images for unattended installation, refer to the

Microsoft knowledge base.

Virtual Disk Size for Windows Server

Windows Server 2008 consumes a lot of disk space when installed. Microsoft says Server 2008 requires 10GB,

but recommends 40GB. Applications take up additional space, and write data and log files that consume even

more space. When a virtual appliance exceeds its allotted disk space, users can easily add a new virtual disk,

however software might not be able to use it effectively.

VMware Studio’s default disk partition size of 4GB for Server 2003 and 16GB for Server 2008 might be too small

for long‐term use. Consider increasing these values in the Virtual Hard Disks section of the Hardware tab. See

Step 4 in the section “Creating a VM Build Profile” on page 83.

On vSphere, users can install virtual appliances onto thin provisioned disk, so it is not really a problem when

you declare virtual disk size much larger than absolutely required.

Table 9-1. Operating System ISO Images

Operating System Name Architecture Possible Variations

Windows Server 2008 R2 with SP1 64‐bit Datacenter, Enterprise, Standard, Web

Windows Server 2003 R232‐bit Datacenter, Enterprise, Standard, Web

64‐bit Datacenter, Enterprise, Standard, Web

VMware, Inc. 83

Chapter 9 Creating a Windows-Based VM

Adding Support for a New Windows OSVMware Studio currently supports only Windows Server 2008 R2, Windows Server 2003 R2, and similar

operating systems. Windows Server systems provide an unattended installer that VMware Studio uses to

automate the installation process.

Creating a virtual appliance from a Windows Server system that VMware Studio does not support requires

entering the desired Windows ISO image filename and the applicable OS Image value in the Windows build

profile. This assumes that the custom Windows OS you want to create is similar to Windows Server 2008 R2

or Windows Server 2003 R2, and that you plan to create a new Windows profile based on one of those two

Windows Server systems using the unattended installer.

For a custom Windows OS that is not similar to Windows Server 2008 R2 or Windows Server 2003 R2, you must

create a new unattend.xsl file (referenced in the build profile) to go with your changes, if the existing version

does not correspond. This requires knowledge of creating unattended installation scripts for Windows.

NOTE The studiocli --newos feature is not applicable to building Windows VM.

Windows Application PackagesVMware Studio can install an application into a Windows‐based VM by executing the application installer

during your VM build. To automatically install the application, it is required to run the installer in silent mode

while using the appropriate installer command line.

VMware Studio offers two ways to install your application:

You can install an application located in a Microsoft Network Folder, by specifying the setup command

line from the Application pre‐install script, which is one of the items you define in the VM build profile.

For example to install an application from a network drive:

\\installserver\crm\setup.exe /s

You can define a VMware Studio Package (VSP) for Windows to encapsulate your application setup, and

host the application setup files in the VMware Studio appliance. VSP for Windows is a file format that

describes the process of installing a Windows application into a Windows‐based VM.

You can use the VMware Studio Web console to package an application as a VSP for Window VM.

See “Creating a Windows Application Package” on page 90.

A VM build profile contains a list of Application Package Repository URLs, designating VSP for Windows files

located on a Microsoft Network Folder, for installing in the virtual machine. Each VSP for Windows file is

loaded and executed in the order listed.

To include a package, either add the URL of a directory containing one or more VSP for Windows files, or add

the URL of a VSP for Windows file. Use the SMB protocol to indicate a Microsoft Network Folder in the URL.

For example, this is the URL of a VSP for Windows file:

smb://installserver/crm/default.vsp

Creating a VM Build ProfileThe build profile contains information about the contents of the VM, virtual hardware configuration of the

VM, and the location where to obtain the OS ISO. The build profile contains all the required information to

automate the building of a VM. This section explains steps to create a VM build profile with the Web console.

Subsequent sections provide reference information about the options in each configuration tab.

You can use the VMware Studio Web console to create a build profile for a Windows‐based virtual machine.

To create a Windows VM

1 Obtain the OS ISO image for a supported version of Windows.

2 In the VMs tab of the Web console, click Create Profile.


84 VMware, Inc.

3 In the Create a New VM Profile dialog box, specify a name for your VM build profile, select a Windows

profile from the list, and click Create Profile.

After you build a VM, it also becomes available in the list as a template to create derived virtual machines.

4 The Editing page appears, where you create the build profile of your VM. The Editing page organizes the


Description – Specifies general information about the VM. See “Description Tab” on page 42 for

details. The Web Console Visual Customization and Welcome Text fields are not supported in a

Windows‐based VM. The end‐user license agreement (EULA) is supported only when packaging the

Windows‐based virtual machine as an OVF or OVA, and is displayed at deployment time.

Hardware – Specifies virtual hardware configuration for the virtual machine, including CPU,

memory, network adapters, CD/DVD, and virtual disks. See “Hardware Tab” on page 43 for details.

Use the drive field to assign a drive letter to a disk partition.

OS – Specifies information about the operating system for the virtual machine. See “OS Tab” on

page 44 for details. (Operating System Configuration included, see “OS Tab” on page 84.)

Application – Specifies the list of VSP for Windows files to install into the virtual machine. See

“Application Tab” on page 86 for details.

Output – Specifies the type of distribution format (OVF, OVA, or ZIP) for the virtual appliance.


Build Settings – Specifies setup of the build environment, such as connection information to one of

many possible provisioning platforms. See“Build Settings Tab” on page 50 for details.

You can use Next and Back buttons to navigate between tabs until you have specified all required fields.

If you try to navigate to the next page without specifying a required field, an error message appears in red

next to the field where you must fix a problem before continuing. Attempting to navigate off the editing

page produces a confirmation dialog box asking if you want to discard your edits.

Each field in the build profile has a help icon (i in a circle) on the right side. Clicking the help icon toggles

between display of contextual help and a list of frequently asked questions (FAQ).

5 After you complete editing a build profile, you can take one of the following actions by clicking a button

on the right side of the window:

Validate – After completion of a build profile, checks the configuration to help you avoid build errors.

A window appears to show the validations that it performs.

Save and Build – Saves your build profile and displays the Build Summary dialog box for review.

To build the VM and begin provisioning, click Build VM. A progress icon appears with a build log

that shows status as the build progresses.

Save and Close – Saves your build profile and closes the editing page. You can save an incomplete

profile. The build profile appears in the VM List, so you can choose to edit or build it later.

Close Without Saving – Closes the editing page and discards changes. A warning appears asking if

you are sure you want to discard changes made during the current session.

Additional Fields for Windows ReferenceThis section describes the new items that are required for a Windows build profile.

OS Tab

The OS Tab contains the basic settings to install Windows in unattended mode. VMware Studio creates an

unattended setup file with settings from the ‘Operating System Installation Configuration’ section, and

provides it to the Windows.

Table 9‐2 describes the new configuration properties in the operating system OS tab.

VMware, Inc. 85


Table 9-2. Operating System Tab New Properties

Field Description

Operating System Installation Configuration

OS Image Specifies the Windows OS edition to install.

Make sure to use the correct OS ISO to match the selected OS Edition.

Windows 2003 provides a separate CD for each edition, while Windows 2008 provides a DVD that includes all the editions.

Product Key The product key code to activate the Microsoft license for Windows Server, in the form XXXXX‐XXXXX‐XXXXX‐XXXXX‐XXXXX.

Windows 2008 can be activated after installation by keeping this field empty.

Owner Name Owner’s full name.

Organization Name Owner’s organization name.

Computer Name Specifies the computer name in the network. Use ʹ*ʹ to generate a random computer name.

License Mode (Windows 2003) Whether the license is per server, per device, or per user.

Concurrent Connections (Windows 2003) Network connections allowed simultaneously. The minimum value is 5.

Time Zone Specifies the local time zone for the Windows virtual machine.

Join Network Specifies network membership settings for this virtual machine.

Workgroup – Name of the workgroup in which the computer participates.

Domain – Name of Windows domain in which the computer participates.

User name – For a domain, name of the user account that has permission to create a computer account in that domain.

Password – For a domain, password of that user account that has permission to create a computer account in that domain.

It is not recommended to join a domain during the VM provisioning, if the VM is going to be deployed more than once. It is preferred to join the domain during the VM deployment, while using the Sysprep tool.

Additional Unattended Configuration VMware Studio automates the OS installation by creating a Windows unattended file with settings based on the VM build profile.

Additional unattended configuration can be provided to merge with the unattended file created by VMware Studio. This is an advanced feature to allow additional customization of the Windows OS installation, such as performing installation or removal of OS components

Windows 2003 uses the unattend.txt format. For additional information see http://support.microsoft.com/kb/155197

Windows 2008 uses the unattend.xml format. For additional information see http://technet.microsoft.com/en‐us/library/cc730695(WS.10).aspx#BKMK_2

Operating System Sysprep Configuration

Perform Sysprep If checked, run Sysprep tool at the end of installation.

The System Preparation tool (Sysprep) is a technology provided by Microsoft to automate the cloning and deployment of Windows operating system. Using Sysprep is recommended when a VM will be deployed more than once, to prepare the system for cloning.

For additional information see http://support.microsoft.com/kb/302577

For Windows 2003 based VMs, the Sysprep tool is copied from the Windows 2003 CD (deploy.cab) into the VM local file system under the C:\Sysprep folder. The Sysprep tool is already installed as part of Windows 2008.

Generate new SID (Windows 2003) If checked, generate a new Security ID (SID). Windows 2008 always generate a new SID when using Sysprep.

Sysprep Command Sysprep command to execute.

http://support.microsoft.com/kb/155197

http://technet.microsoft.com/en-us/library/cc730695(WS.10).aspx#BKMK_2

http://support.microsoft.com/kb/302577


86 VMware, Inc.

Application Tab

Table 9‐3 describes the configuration properties available on the Application tab.

Sysprep Configuration File Contents of the Sysprep answer file. Specify any required Sysprep settings when running the VM for the first time. The default content provided by VMware Studio is using a special variable convention to set some Sysprep settings from the OS installation settings. For example, the Product Key can be retrieved by using $(ProductKey) in the Sysprep configuration file content.

Windows 2003 uses the sysprep.inf format. To create a Sysprep.inf answer file for use by Sysprep, you can use the Setup Manager tool that is included on the Windows 2003 CD and also in the Microsoft Windows 2003 Resource Kit.

Windows 2008 uses the sysprep.xml format. To create a sysprep.xml answer file for use by Sysprep, you can use the Setup Manager tool that is included in the Windows Automated Installation Kit (AIK). To locate the AIK, search for “AIK download” on the Microsoft Web site.

User Accounts

Administrator Password Password of the Administrator account for the Windows VM. Confirm.

Add User Click the Add User button to add a new user to this Windows VM. You supply user name, password, confirm password, full name (optional), and group membership for the new user.

To delete a user, click the Remove User link in the upper right corner.

If needed, use the Application pre‐install script to enable and set the password of the ‘Guest’ user account.

Table 9-2. Operating System Tab New Properties (Continued)

Field Description

Table 9-3. Application Tab Configuration Properties

Field Description

Application Packages

Application Package Repositories A list of Application Package Repositories with VSP for Windows files.

Use the Move Up and Move Down buttons to change the installation order.

Add | Add URL | Edit | Remove You can include a VMware Studio Windows Package for Windows either from the VMware Studio appliance Windows packages repository or from any Microsoft Network Folder.

To add an application package from the VMware Studio appliance packages repository, click Add, A dialog box shows a list of packages in the VMware Studio appliance Windows packages (under the /opt/vmware/depot/winrepo directory). Select the Windows package or packages to be included as part of the VM, and click Add in the dialog.

VMware Studio packages can be installed from any Microsoft Network Folders by specifying the smb protocol, as in this example:

smb://appstorage/windows/sharepoint/sharepoint.vsp

To add an application package or directory of packages to your VM, click Add URL, enter the URL of the package or directory on a Microsoft Network Folder, and click OK.

To change the URL of an application package or directory, click Edit, modify the URL, and click OK. To delete an entry, click Remove.

See “Windows Application Packages” on page 83 for details about application repositories.

Application Installation Customization

Application PreInstall Script Script that runs after installation of the operating system, but before the installation of application packages during virtual machine provisioning.

Application PostInstall Script Script that runs after the installation of application packages during the virtual machine provisioning phase.

VMware, Inc. 87


Building a VM from the Build ProfileAfter you complete a build profile, you can build a VM from it. First click Validate to verify profile contents.

If the VM profile validates, click Save and Build. Then in the Build Summary dialog box, click Build VM. This

starts building a transient VM on the provisioning platform.

To retain the transient VM without cleaning up after the build, in the Build Summary dialog box, click

Advanced Build Settings. This makes visible a check box saying “Retain transient VM on the virtualization

platform and skip provisioning cleanup.” Clicking the check box allows you to test the VM on the provisioning

platform before deploying it elsewhere.


a build log appears to inform you of each completed step in VM provisioning. To eventually cancel a build in

progress, click Cancel under the status icon.

You can launch multiple builds concurrently: navigate to another build profile and click Save and Build again.

You can also rebuild a profile before another build completes.

The Windows VM may reboot several times during installation. If you encounter problems during the build

process, see “Troubleshooting VM Builds” on page 145 for diagnostic information.

To see the build summary, various logs, and discovery reports: in the VM List, click the VM name > Finished

(or Failed, or Canceled). The Details dialog box appears, with the following tabs:

Build Summary – provides details of the build profile configuration.

Verbose Log – provides a detailed log of each completed phase of the build process.

Debug Log – provides details of each completed build phase, including debugging information.

Application Install Log – provides a log of the installation messages as the operating system and each

application package gets installed into the virtual machine. Reviewing the install log can help when

troubleshooting package dependency errors if more packages are required.

Discovery Reports – provides information about packages, hardware settings, and operating system.

Each build is stored in the VMware Studio appliance’s file system. You can delete older builds when they are

no longer needed. See “Reiterating the Build Process” on page 88 for more information.

Testing the Generated VMAfter you have successfully built a VM, you can obtain the virtual machine distribution file by clicking on the

ZIP or OVF link (depending upon which type of output file you specified) in the Download column of the

VM’s Previous Build list.

You should click on your virtual machine distribution file and test the completed VM by deploying it in its

intended environment to ensure that the VM and any applications that it contains work properly. You can

download a ZIP file for testing. Do not download an OVF for testing, because if you do, you get only the OVF

and not the associated VMDK files. Instead, test the OVF by right clicking on the URL, copying it, and pasting

it into the Import Appliance or Deploy OVF Template dialog boxes of ESX 3.5 or later, respectively.

Verify that all application packages are installed correctly and that your boot scripts run correctly. Check that

your application starts correctly.

If you plan to distribute this virtual machine as a virtual appliance to your customers, see the User’s Guide to

Deploying vApps and Virtual Appliances for information about deployment of a virtual appliance.

IMPORTANT With vSphere, you can monitor the OS build and application install on the provisioning server.

After prebuild, a thumbnail of the server console appears, refreshed every 5 seconds, alongside the build log.

For a full‐size image, click on the thumbnail. Watching a build helps greatly if something goes wrong.


88 VMware, Inc.

Reiterating the Build ProcessMany developers find that an easy way to a create a Windows VM is to build it initially just containing the

operating system, then add application packages and dependencies in successive builds. Each successful build

occupies space, but you can delete them.

To delete a build using the VMware Studio console, select a VM from the VM List, locate the build instance

you want to remove, and click Delete. You can also delete a build using the studiocli -d command.

Provisioning a Windows ISO in vSphere DatastoreTo optimize Windows VM build performance when provisioning through vCenter Server or directly on

ESX/ESXi hosts, VMware Studio requires the specified Windows ISO image in the vSphere datastore.

By default VMware Studio 2.6 copies the Windows ISO image over to the datastore, and places it into the iso subdirectory, that is, the [datastore] /iso directory. If this directory does not already exist, VMware Studio

creates it, except with ESX/ESXi 4.1, where you must create the directory yourself to prevent the build hanging.

The reason for copying the ISO image into the provisioning datastore’s iso directory is to speed up the second and subsequent Windows builds.

If you want VMware Studio to copy the Windows ISO somewhere else, you can specify an alternate directory

in the profile’s vadk:DatastoreISO item. The directory that you specify must exist before the build, otherwise

VMware Studio reverts to its default and copies the ISO image to the datastore’s iso directory, creating the directory if necessary, except with ESX/ESXi 4.1 as mentioned above.

In the example below, the Windows 2008 R2 ISO is placed in datastore2 under the ISO directory because datastore1 was nearly full and needed to conserve space for VM provisioning.

<vadk:ISOvadk:path="file:///opt/vmware/www/ISV/ISO/en_windows_server_2008_r2_standard_enterprise_datacent

er_web_x64_dvd_x15-50365.iso" vadk:md5sum="" vadk:packageRepoPath="" vadk:containFiles=""/>

<vadk:DatastoreISOvadk:path="[datastore2] ISO/en_windows_server_2008_r2_standard_enterprise_datacenter_web_x64_dvd

_x15-50365.iso"/>

Once the profile is updated and saved, you are ready to build your Windows VM using the Windows ISO in

the alternate location.

Currently the same Windows ISO must be present under /opt/vmware/www/ISV/ISO in the Studio appliance (as in the example above) for the build process to proceed, even though that copy of the ISO image is not

actually used during provisioning.

VMware, Inc. 89

10

This chapter contains the following sections:

“About VMware Studio Package for Windows” on page 89.

“Repository of Windows Application Packages” on page 89

“Creating a Windows Application Package” on page 90.

About VMware Studio Package for WindowsVMware Studio Package (VSP) for Windows is a file format that describes the process of installing a Windows

application into a Windows‐based VM. VSP for Windows works together with existing application installers,

and defines the command line and scripts to run the installer in silent mode. Using a VSP for Windows has the

following key features:

Supports all silent application installers (MSI, InstallShield, and others).

Provides a container for application setup files.

Allows multiple command lines and scripts (Shell, JScript, VBScript).

Handles execution errors.

Reboots the operating system as needed.

Permits reuse of the package definition with multiple VM build profiles.

VSP for Windows can also be used to perform simple application installation tasks, such as copying files and

updating the registry. For example, you can provide a shell script to copy files from the package folder to the

VM’s local file system. Usually the installer (such as MSI) updates the registry. VSP for Windows should not

be used as a replacement for existing application installation technologies.

The VSP for Windows file format is similar but not identical to the VSP for Linux produced by VMware Studio

Plugin for Eclipse.

Repository of Windows Application PackagesThe VMware Studio appliance contains a Windows package repository that hosts user‐defined VSP for

Windows, for installing in Windows‐based VMs. Each Windows package is assigned a directory, which

contains the VSP file format and additional files used to install the application, such as executables, scripts,

MSI files, and so forth.

A VSP for Windows is placed on the VMware Studio appliance under the folder:

/opt/vmware/depot/winrepo

VMware Studio contains a Samba server to allow remote access to the Windows packages repository. Using

root user credentials, you can access it for uploading setup files in the following Microsoft Network Folder:

\\<studio-address>\depot\winrepo

Packaging a Windows Application 10


90 VMware, Inc.

Creating a Windows Application PackageUse the Library tab to create a VSP for Windows.

To package a Windows application

1 Identify the application setup files and the required command to run the silent installer.

2 In the VMware Web console, click Library > Windows > Create Package.

3 In the Create a New Windows Package dialog box, specify a name for your package. Spaces are not

allowed. Select a template from the list, use the ‘Other’ template for a clean package definition.

Click Create. After you create a Windows package, it becomes available as another template in this list.

4 On the Editing page, optionally provide a description of the package.

5 Upload all files required to install your application into the package folder, which can be reached either

locally on the VMware Studio appliance, or remotely as a Microsoft Network Folder by authenticating as

the VMware Studio root user.

VMware Studio Appliance Folder: /opt/vmware/depot/winrepo/<package-name>Microsoft Network Folder: \\<studio-address>\depot\winrepo\<package-name>

6 Within the Command 1 section, define the appropriate executable or script to install the application in

silent mode. Several command types are supported.

Program – Execute the program defined in the command field.

Shell – Run the shell script defined in the script field using the Command Interpreter (CMD).

VBScript – Run the VBScript defined in the script field using Windows Script Engine.

JScript – Run the JScript defined in the script field using Windows Script Engine.

For example, the following command executes the Firefox installer from the package directory:

“Firefox Setup 3.0.6.exe” -ms

As another example, the following commands kicks off an MSI‐based installation:

msiexec /i crm.msi ADDLOCAL=ALL /NoRestart /Passive

During package installation, the package Microsoft Network Folder is mapped as a network drive and

used as the working directory of the executed commands and scripts. Use relative paths in the commands

and scripts to access files in the package directory.

7 For various command exit codes, add the action to perform in that case. Define any additional exit‐code

handling that your application requires by clicking the Add Result button. Use the asterisk (*) exit code to define a default action for exit codes that are not listed. When defining actions, you can choose from the

following list of available actions.

OK – successful execution.

Reboot immediately – reboot now before continuing to the next command or package.

Reboot on installation end – reboot after installing all packages.

Reboot on package installation end – reboot after all commands in the current package are executed.

Reboot immediately and repeat command – reboot now and re‐execute the current command.

Fail ‐ execution failed.

To add exit codes, and for a list of registered exit codes, see “Registered Exit Codes” on page 91.

8 If installation of your application requires another command, click Add Command and type it under

Command 2 (and up). Repeat this step for as many commands as you need.

9 Click Save and Close to retain your changes. Your application appears in the list of Windows Packages.

VMware, Inc. 91

Chapter 10 Packaging a Windows Application

Registered Exit Codes

These are the registered exit codes that define the default behavior. Click Add Result to register new exit codes

to override the default behavior.

0 – OK – successful execution.

1641 – Reboot immediately – reboot now before continuing to the next command or package.

3010 – Reboot on installation end – reboot after installing all packages.

* (Other) – Fail – execution failed.

Environment Variables when installing Packages

VMware Studio supports the following environment variables in commands and scripts:

PACKAGEDIR – Location of current package folder.

This example shows using an absolute path to the MSI file:

msiexec /i “%PACKAGEDIR%\application.MSI” /Passive

REPOSITORYDIR – Location of the VMware Studio Windows packages repository.

This example shows using MSI file from another package:

msiexec /i “%REPOSITORYDIR%\crm\application.MSI” /Passive

LOGDIR – Location of the logging directory. Log files created under this directory are copied to the status directory of the VM build instance in the VMware Studio appliance.

This example enables the log file during MSI:

msiexec /i CRM.msi /Lime "%LOGDIR%\crm.log" ADDLOCAL=ALL /NoRestart /Passive


92 VMware, Inc.

VMware, Inc. 93

Developing a vApp for vSphere


94 VMware, Inc.

VMware, Inc. 95

11

This chapter documents use of the VMware Studio Web console for building a vApp.

“Introduction to Building a vApp” on page 95

“Applications in a vApp” on page 96

“Importing vApp Profiles” on page 100

“Web Console Tab Reference” on page 96

“Building a vApp Build Profile” on page 99

“Testing the Generated vApp” on page 100

A vApp is a prebuilt software solution consisting of one or more virtual machines (VMs) and applications,

which are potentially operated, maintained and monitored as a unit. The OVF 1.0 standard format is required

to represent the combination of multiple virtual machines and applications.

Introduction to Building a vAppThe vApp unifies a set of VMs and applications, defining their dependencies and interfunctionality, including

packaging, start order, and resource allocation.

You can mix Linux‐based VMs and Windows‐based VMs together in a vApp.

Prerequisites

To build a vApp you must have one or more virtual machine build profiles. If a virtual machine is not built,

the vApp build process attempts to build it. For details about VM build procedures, see Chapter 4, “Creating

a Linux‐Based VM,” on page 35 or Chapter 9, “Creating a Windows‐Based VM,” on page 81.

To run a vApp, you need a virtualization product platform that supports OVF 1.0, such as VMware vSphere

or vCloud Director.

Creating a vApp Build ProfileJust as you created and built virtual machines using the VMs tab of the VMware Studio Web console, you

create and build vApps using the vApps tab.

To create a vApp

1 In the vApps tab of the Web console, click Create Profile. In the Create a New vApp Profile dialog box,

choose a name for your vApp, select a profile from the list, even if only one template appears, and click

Create Profile.

After you successfully save a vApp profile, it becomes available in this list and can be used as a starting

point to define another vApp build profile.

Creating a vApp from VM Builds 11


96 VMware, Inc.

2 The vApp wizard appears, where you can edit the build profile of your vApp. This wizard organizes the


Description – General information about the vApp. See “Description Tab” on page 97 for details.

VMs – The virtual machines to include in the vApp. See “VMs Tab” on page 97 for details.

Start Order – Start order of VMs in this vApp. See “Start Order Tab” on page 98 for details.

Resources – Controls vSphere resources for virtual machines in this vApp. See “Resources Tab” on

page 98 for details.

Output – Selects output format, virtual machine which holds the Application URL, and OVF settings.


3 In the Description tab, specify the product name and version, at minimum.

4 In the VMs tab, click Add VMs, select at least one VM build profile, and click Add.

Do this at least once. Most vApps contain more than one VM.

5 In the Start Order tab, you can control power on and power off sequence of the VMs by placing virtual

machines into different boot groups and specifying start and stop delay.

6 In the Resources tab, you can control the CPU and memory shares that vSphere allocates for each VM.

For information about boot groups, CPU shares, and memory shares, see the vSphere documentation.

7 In the Output tab, you must specify a File Name for the resulting vApp. You can also enable OVA archive

in addition to OVF, control the method of IP assignment, and add new OVF properties.

8 (Optional) Click Validate to check your settings.

9 To build the vApp, click Save and Build and in the Build Summary dialog box, click Build vApp.

The Save and Close button writes to disk the settings you created. The Close Without Saving button

discards your settings.

If the build is successful, your new vApp appears in the list of vApp profiles under the vApps tab.

If the build fails, diagnostic messages appear in the Build Summary dialog box.

Applications in a vApp

You include Linux applications by specifying them in the Application Package Repositories list for one of the

child Linux VMs of this vApp, as described in “Application Packages” on page 39.

You include Windows applications by using the Library > Windows tab to create packages for applications,

or to import existing packages for one of the child Windows VMs of this vApp, as described in “Creating a

Windows Application Package” on page 90.

If you have not included any applications that your vApp needs, you can rebuild the containing VM.

Web Console Tab ReferenceThese sections document all fields in different tabs of the Web Console.

“Description Tab” on page 97

“VMs Tab” on page 97

“Start Order Tab” on page 98

“Resources Tab” on page 98

“Output Tab” on page 98

NOTE Any vApp must be represented according to the OVF 1.0 standard. The OVF 0.9 specification did not

allow multiple virtual machines to be represented in a collection.

VMware, Inc. 97

Chapter 11 Creating a vApp from VM Builds

Description Tab

Table 11‐1 describes the configuration properties available on the Description tab.

VMs Tab

Table 11‐2 describes the configuration properties available on the VMs tab.

Table 11-1. Description Tab Configuration Properties

Field Description

Information

Product Name Name of the vApp that you are building. This name is used to show this vApp in the vSphere inventory and in the Summary tab of vSphere.

Version Version of the vApp. This is shown in the Summary tab for this vApp in the vSphere client.

Full Version Arbitrary text string used to display version information of the vApp, often similar to Version. This is shown in the Summary tab for this vApp in the vSphere client.

Product URL URL on the companyʹs Web site where customers can find information about this vApp This is shown in the Summary tab for this vApp in the vSphere client.

Vendor Company name of the vApp vendor. This is shown in the Summary tab for this vApp in the vSphere client.

Description Description of the functionality that this vApp provides. The description displays when the vApp is imported into ESXi as an OVF and in the Summary tab for this vApp in the vSphere client.

Vendor URL Vendor URL to your companyʹs Web site. This is shown in the Summary tab for this vApp in the vSphere client.

Application URL URL to the Web console for the application provided in this vApp. The ${app.ip} keyword in the URL resolves to the VMʹs IP address, after deployment, at runtime. In the Output page for vApps, the Application URL Configuration field contains a menu where you can specify which VM you want represented in ${app.ip}.

End-User License Agreements

Add EULA Click the Add EULA button to add an end‐user license agreement (EULA).

EULA The full text of your EULA. The user is presented with this license when running the vApp for the first time and must accept this license agreement. If no EULA is defined, then the vApp boots without user intervention.

You can add more than one EULA by clicking the Add EULA button again. You can delete a EULA by clicking the Remove EULA link on the right above its EULA.

Table 11-2. VMs Tab Configuration Properties

Field Description

VM List

Profile Name Name of the virtual machine profile.

Build The drop‐down box allow you to select an existing build, or rebuild from its profile. The Build from profile choice means that VMware Studio rebuilds the VM from its profile each time you build the vApp.

Location Location of the OVF or OVA file from which this vApp is built.

Remove Click the Remove button to delete a VM from the vApp.

Add VMs Click the Add VMs button to add a VM to this vApp.


98 VMware, Inc.

Start Order Tab

Table 11‐3 describes the configuration properties available on the Start Order tab.

Resources Tab

Table 11‐4 describes the configuration properties available on the Resources tab.

Output Tab

Table 11‐5 describes the configuration properties available on the Output tab.

Table 11-3. Start Order Tab Configuration Properties

Field Description

VM List

Boot Group Virtual machines that are in a boot group are started at the same time, based on the specified start action.

Start Action At start time, whether to power on the virtual machine, or do nothing.

Start Delay (sec) The number of seconds to wait for power on, if not waiting for tools. The start sequence continues after this delay.

or when tools is ready If selected, wait until VMware Tools is running before initiating applications.

Stop Action At stop time, whether to power off, suspend the virtual machine, or shut down the guest OS.

Stop Delay (sec) The number of seconds to wait for power off.

Table 11-4. Resources Tab Configuration Properties

Field Description

VM List

CPU Shares The priority for this virtual machine relative to others when nonreserved CPU is available.

Memory Shares The priority for this virtual machine relative to others when nonreserved memory is available.

Table 11-5. Output Tab Configuration Properties

Field Description

Distribution Format

File Name Name of the vApp file. This name is visible to users when they download the OVF or OVA package.

Output Format Use OVF format for deploying this vApp on any VMware Platform.

Use OVA (archive) format for faster deployment by streaming the vApp.

Application URL Configuration

Application URL VM When you specified the Application URL for this vApp, the VMʹs IP address is substituted into the ${app.ip} variable in the URL. Because a vApp can have several VMs, you must specify which of the VMs comprising the vApp will have its IP address substituted into the ${app.ip} variable. Select the VM to which the vApp’s Application URL should point.

Enabled IP Protocols

IPv4 By default IPv4 is always selected, so this check box is grayed out.

IPv6 Click this setting to use IPv6 address format. VMware Studio does not support IPv6‐only network environments.

IP Address Deployment Choices (in vCenter)

Do not prompt for any networking parameters

Click this button to avoid asking the vSphere administrator at deployment time to provide network parameters, which will be set from DHCP, or failing that, manually. This option prevents VMware Studio from automatically generating any OVF networking properties.

VMware, Inc. 99

Chapter 11 Creating a vApp from VM Builds

Remember that vCloud Directory 1.0 does not support custom OVF properties for a vApp.

Building a vApp Build ProfileAfter you have completed a build profile, you can build your vApp. First click Validate to check for minor

errors. If the vApp profile validates, click Save and Build.


a build log appears to inform you of each completed step in vApp provisioning. To cancel a build in progress,

click Cancel under the status icon.

When the build completes or fails, VMware Studio informs you whether this build was successful or not. If the

build was successful, click Contents to show the VMs that are contained in the vApp.

If you encounter problems when building a virtual machine, see “Troubleshooting VM Builds” on page 145

for diagnostic information.

Prompt for all networking parameters

Click this button to have the vSphere administrator set all networking parameters when installing a VM through vCenter Server. This option instructs VMware Studio to automatically generate OVF networking properties.

Prompt for an IP address, and retrieve additional parameters from an IP Pool

Click this button to prompt the vSphere administrator with networking parameters based on the IP Pool, using either DHCP, a specific fixed or transient address, or both. When you click this button, two choices appear underneath, as described below.

Both the vApp and all the VMs within the vApp must specify this option, if you want the vApp to prompt and retrieve additional network parameters from an IP Pool.

DHCP (check box) During deployment the administrator is given the option to use a DHCP server for setting up the VM, and networking is automatically configured by the VAMI agent.

Fixed or Transient (check box)

During deployment vSphere gives the administrator the option of a fixed or transient IP address for the VM. Networking is automatically configured by the VAMI agent. This requires OVF 1.0 or OVA, and an IP Pool configured on the vCenter Server.

OVF Properties

Add | Edit | Remove Click Add to add an OVF property. Click Edit to change an existing OVF property. Click Remove to delete an OVF property.

Key Key to OVF Property.

Label Label for OVF Property.

Description Description of OVF Property.

Type List of OVF property types supported by Studio. These types are enforced by VMware vSphere during deployment.

Default Value String, unsigned integer, string choice, Boolean value, or IP address of this property.

Maximum Length Maximum length that can be specified for a string property.

Range Low and high values that can be specified for an integer property.

ValueMap List of possible values for a string choice property.

User Configurable Whether to prompt user to allow changing of property.

ovf:type Each Property element in a ProductSection must be assigned an ovf:type attribute. Valid types look like CIM data types and are listed in the OVF specification.

ovf:value Optional attribute ovf:value provides a default value for a Property element.

ovf:qualifiers Optional attribute ovf:qualifiers specifies CIM type qualifiers for a Property, with multiple qualifiers separated by commas.

vmw:qualifiers Optional attribute vmw:qualifiers gives VMware‐specific qualifiers for a Property.

Table 11-5. Output Tab Configuration Properties (Continued)

Field Description


100 VMware, Inc.

Inspecting the vApp Build

After a build, you can view various logs to see what happened during the build. In the list of vApp profiles,

select a vApp, and click Build Log to see a recap of build progress.

To see the vApp build summary and verbose log, underneath the Status heading click Finished (or Failed).

The Build (vApp) Details dialog box appears, with the following tabs:

Build Summary – provides details of the build profile configuration and EULAs.

Verbose Log – provides a detailed log of the vApp build.

Deleting a vApp Build

Each vApp build is stored in the file system. You might want to delete older vApp builds when they are no

longer needed. To do this, select an old build in the vApp’s Build Instance list, select the Delete check box, and

click Delete Instance.

Testing the Generated vAppAfter you have successfully built a vApp, you can obtain the vApp distribution by clicking in the Download

column of the vApp list on the OVF 1.0 or OVA link (depending upon which type of output file you specified

for build output). Likewise, you can obtain the OVF or OVA files for old builds in the Previous Builds list.

You can test the completed vApp by deploying it in the intended environment and verifying that the vApp

and any applications that it contains work properly. You can deploy vApps only through vCenter Server or on

vCloud Director, not on ESXi hosts or Workstation. Check that your application starts correctly. Ensure that all

packages are deployed properly and that boot scripts run correctly.

Importing vApp ProfilesYou can import vApp build profiles/templates into VMware Studio in the following circumstances:

When you upgrade to a newer version of VMware Studio.

When you manually create a vApp build profile.

Using a profile created by another user on another VMware Studio appliance.

To import an existing vApp profile into VMware Studio

1 Place the vApp build profile on the host where the Web browser runs.

2 In the VMware Studio Web console, click the vApps tab and click the Import Profile button.

3 A dialog box appears where you must enter the name of the vApp. You can click the Browse button to

find the profile on your computer.

4 Click Import Profile. VMware Studio creates a new vApp profile based on the imported build profile, and

adds it to the list of vApps.

5 VM build profiles that are referenced by this vApp build profile must be imported into VMware Studio

before you can build this vApp.

NOTE It is not possible to publish vApp updates as a unit. You must separately update the constituent VMs

of a vApp.

VMware, Inc. 101

12

VMware Studio help you create VMs and vApps that you can ship as virtual appliances. This chapter describes

the best practices for creating virtual appliances.

“Outline of Virtual Appliance Build Procedure” on page 101

“VMware Recommendations” on page 101

Outline of Virtual Appliance Build ProcedureYou begin building a virtual appliance the same way that you create a VM or a vApp: by creating a profile that

defines a container and its included software packages.

To manage the virtual appliance life cycle

1 Define a build profile with the features you want. Choose an operating system for the VM, and application

packages to include. You can configure the welcome screen, first boot script, and subsequent boot scripts.

See “VMware Recommendations” on page 101 for advice.

2 VMware recommends that you include the update agent when creating virtual appliance. Follow the

steps for establishing an update repository using the “Management Tab” on page 46.

3 Build the VM. VMware Studio relies on a virtualization product platform to assemble the files required

to build (or provision) your virtual appliance.

4 If you are building a multiple‐VM appliance, called a vApp, repeat the steps above to create other VMs.

When you have the set of VMs that you need, package them using the vApps > Create Profile interface.

5 Distribute the output as OVF or OVA.

6 On an ongoing basis, you might be required to release patches for your virtual appliances and vApps that

are deployed at customer sites.

When virtual appliances are deployed, end‐users can manage them from the VMware Studio Web console.

Administrators can manage a vApp or collection of virtual appliances from vCenter Server. End‐users can

check for and install appliance updates using the Web console, if you enabled update service for the virtual

appliance and established an update repository.

VMware RecommendationsThe remaining sections in this chapter give suggestions or recommendations for choices you make during the

creation of a virtual appliance or vApp. Some choices are a trade‐off of portability for new functionality.

Choosing OVF Version

VMware used to suggest delivering OVF 0.9 output files so your virtual appliance can run on older VMware

product platforms such as ESX/ESXi 3.5 and VirtualCenter. If you create a vApp with multiple VMs, you must

deliver OVF 1.0 or OVA output files, and the vApp can run only on VMware vSphere.

Guidelines for Creating Virtual Appliances 12


102 VMware, Inc.

The downside of OVF 0.9 is that it loses any OVF properties you have defined, and your virtual appliance

cannot benefit from automatic network configuration that OVF 1.0 deployment into VMware vSphere

provides. VMware Studio generates both OVF 0.9 and OVF 1.0 descriptors when you select OVF output, so

you can easily deliver both formats to customers.

OVF 1.0 is required for deployment on vCloud Director, and vSphere has supported it since the 4.0 release, so

it is the best choice going forward. The OVF 0.9 format is deprecated, and support for it will be removed in a

future release.

Choosing Virtual Hardware Version

VMware recommends specifying virtual hardware version 4 (vmx-4) in the VMs > Hardware tab. This virtual hardware version can run on all current and recent VMware platforms. If your virtual appliance requires more

than four processors or more than 64GB memory and is designed to run on vSphere, you should select virtual

hardware version 7. VMware Workstation limits VMs to 8 GB memory even with virtual hardware version 7.

User Accounts

VMware recommends that you not give away the root or administrator password for your appliance. You can

modify the first‐boot script to request that the end‐user supply a custom root password at deployment time.

Alternatively, you can create additional user accounts that have non‐root privileges, and inform customers

about those accounts to enforce limited access to your virtual appliance.

Include Update Agent

When building Linux‐based VMs, VMware strongly recommends enabling the update repository. You do this

on the VMs > Management tab by adding the update service to the list of management services. Then follow

procedures in Chapter 7, “Managing a Linux Update Repository,” on page 67. Windows‐based VMs do not

allow the option of an update repository.

Footprint Reduction

VMware recommends both methods of reducing the size of generated VMs: redundant package elimination

and unnecessary file removal. See “Operating System Footprint Reduction” on page 60

Partitioning Disk for System and User Data

VMware recommends that you keep user and configuration data on separate disks. This aids in upgrading the

appliance to a newer version. You can decommission the virtual appliance after unmounting the data disks

and mounting them on the new virtual appliance.

VMware Ready Virtual Appliances

The virtual appliances that VMware Studio creates are almost VMware Ready. The only gap is that data in the

product section must be filled in. Product name and version are required, but other fields can be empty. In the

current release, Product Name is filled in from the VM profile name, and 1.0.0.0 is the default version number.

For details about the VMware Ready program, see http://www.vmware.com/partners/vmware‐ready.

Guidelines for Adding Kernel Extensions

To insert a custom kernel module, you can run the modprobe command from the First Boot Script to load your

kernel module. The modprobe(8) page says that modprobe expects an up‐to‐date modules.dep dependencies file, as generated by the depmod command; see depmod(8). To make alterations to the Linux kernel, you can use

the VMware Studio feature to add support for custom Linux operating system. This involves creating an ISO

image of the operating system with altered kernel, then adding it to the list of OS templates for choosing a

profile. For more information, see “Retrieve OVF Properties” on page 105.

VMware, Inc. 103

13

You can use the VMware Studio Web console to create and build virtual machines and vApps. You can also

use the VMware Studio command‐line interface to integrate with an existing application build system,

automate the build process, and integrate with your source control system. This is especially useful when

developing a virtual machine or vApp to ship as a virtual appliance.

This chapter describes the VMware Studio command line interface and includes the following topics:

“Using the Command Line” on page 103

“Retrieve OVF Properties” on page 105

For information about build profile files, see Appendix D, “Editing XML Build Profiles,” on page 127.

Using the Command LineVMware Studio provides a command‐line interface to build, query, and clean up virtual machines and vApps.

To use the command‐line interface, log in to the VMware Studio console by accessing the VMware Studio

welcome screen and selecting the Login option. Alternatively, you can use a terminal emulator to make an SSH

connection to the VMware Studio appliance. After you log in as root, run the following command:

studiocli

Table 13‐1 describes the options available for the studiocli command.

Building from the Command Line 13

Table 13-1. Options to the studiocli Command

Option Alternate Description

-b --buildstatus Displays the status and log messages for a specified build instance or all instances per build profile. For example, to list all build instances:

studiocli --buildstatus

To list the status of build instance myVA/myvApp with extra verbosity, run:

studiocli --buildstatus --verbose --instance myVA/myvApp

To list the status of all build instances for build profile myBuildProfile.xml, run:

studiocli --buildstatus --verbose --profile myBuildProfile.xml

This subcommand takes the --key, --value, and --nomap options.

-c --createbuild Creates the virtual machine/vApp based on a given build profile. Also generates a update repository if a repository is specified in the build profile. For example, to build a virtual machine, enter the following command:

studiocli --createbuild --verbose --profile /<path>/<mybuildprofile.xml>

-C --convertprofile Convert a Studio 1.0 or 2.0 profile into a Studio 2.1 or 2.5.0.0 profile. Profiles created in earlier versions of Studio must be converted before they can be used. Simply opening them in the Web UI converts them automatically.


104 VMware, Inc.

-d --deletebuild Deletes a build instance for a specified build profile including its virtual machine, vApp, log and update files. For example, to delete all files associated with the build instance myVA/myvApp, run:

studiocli --deletebuild --instance myVA/myvApp

-D --debug Enables debug mode. Normally, after a build, the transient virtual machine or vApp is deleted from the provisioning engine. For help debugging, this option prevents the transient virtual machine from being deleted, leaves helpful log files in place, and does not delete temporary files used in the build process. Log files to check are /var/log/vmware-studio-agent.log and /root/postinstall.log. This option also enables verbose debugging messages (-vv option described below).

-h --help Show subcommands of studiocli, and possible options to each subcommand.

-i --instance A unique tag for each build. The value must be less than 16 characters long and can be composed of the letters a‐z, A‐Z, the numbers 0‐9, and the characters ‐ and _. By default, a build instance will be generated by VMware Studio.

-I --importvm Import a virtual machine. The imported VM can be used as input VM for existing VM provisioning. In addition to the VM, VMware Studio also needs a build profile for existing VM provisioning. If possible, specify the original build profile that matches the imported VM with the profile option: ‐p http://.../example.xml

Before provisioning, you can change this base profile, for example by adding new packages or creating new users. If you do not provide the original profile, VMware Studio tries to generate one for you.

studiocli --importvm <http://vmurl./ovf/ova/zip> --profile /<path>/<mybuildprofile.xml>

-k --cancelbuild Cancels the build currently in progress. If the virtual machine is currently being provisioned on the server, it is deleted from the server.

-k -v ‐-key --value Only valid after -b or --buildstatus. Searches for all the build instances matching the <key> and <value>. <key> are ones on the left hand side of the build status output and <value> are on the right hand side.

-m --mkpkg Helps in the creation of application packages. Using this tool you can create either DEB or RPM application packages. For details, see Chapter 5, “Packaging a Linux Application,” on page 55

--nomap Disables the mapping of [VADK.localIP] to the IP address of VMware Studio. Used by the Management UI. Only valid after -b or --buildstatus.

-n --newos Specifies a new OS, usually one that is not on the officially supported list, for system and package discovery. VMware Studio generates a build profile in this process. Must be followed by the -p or --profile option.

-o --output After -C or --convertprofile, specifies output filename for conversion.

-p --profile Specifies the qualified filename of a build profile. Generic template build profiles can be found under /opt/vmware/etc/build/templates. VMware Studio generated VM profiles are located at /opt/vmware/var/lib/build/profiles, and vApp profiles are located at /opt/vmware/var/lib/build/vapp_profiles.

-P --profiletype Shows the type of a profile whether a VM or vApp. A profile name must be specified

--sif Exports, imports, and lists a Studio Interchange Format (SIF) file containing all the dependent parts of a virtual appliance build, for ease of sharing and rebuilding. See Table 13‐2, “Options for the SIF Subcommand,” on page 105.

-K --keeponerror This option preserves the VM and temp files when a error occurs. It is new option for studiocli --createbuild.

-t --validateprofile Validates a given build profile by testing resource authentication, availability, and connectivity. For example, to validate your build profile before building your virtual machine/vApp, run the following command:

studiocli --validateprofile --profile /<path>/<mybuildprofile.xml>

-v --verbose Increases descriptive output with the first invocation. Enables debug output with subsequent invocations (-vv).

Table 13-1. Options to the studiocli Command (Continued)

Option Alternate Description

VMware, Inc. 105

Chapter 13 Building from the Command Line

Retrieve OVF PropertiesThe ovfenv command normalizes all the various ways to get OVF properties, so your software can just call it

and not worry if the OVF properties came VMware Tools or from a CD that vCenter Server constructed and

made available to the VM. Like studiocli, ovfenv is in the /opt/vmware/bin directory. Here is usage:

ovfenv [-h|--help] [-d|--dump] [-f|--file <ovfenvfile>] [-i|--id <VM_ID>] [-k|--key <key>] [-v|--value <value>]

This command shows the value of an OVF property, no matter how the properties were presented to this VM.

If you specify a property file after --file, the command looks only in that file. Otherwise the command looks

for OVF properties in the following order:

1 The VM’s default property file

2 The VMware Tools guestinfo structure

3 CDROM drive – Studio 2.5 and later support the OVF transport=iso flag. When an administrator

deploys a VM on vSphere, answering client prompts for property values, vCenter Server constructs an

ISO image containing these property key/value pairs and makes the image available on the appliance’s

CD drive. (The transport=iso flag is not supported by ESXi, vCloud Director, or Workstation.)

Optionally, this command allows a property value to be modified. If you specify a value after --value, the guestinfo structure is modified, and either the VM’s default property file or the given property file is

updated. If the properties have been presented to the VM from a CDROM only, this command will not be able

to modify them on the CDROM. Also, this command can not create a property if it does not already exist.

Table 13‐3 shows sample commands using most possible options.

Table 13-2. Options for the SIF Subcommand

Subcommand Option Alternate Description

--sif (import) -i <SIFfile> --import <SIFfile> Imports a SIF file.

-b <dir> --basedir <dir> Base directory for importing the files. By default, the files are extracted to the current directory. To copy the files to pre‐set Studio locations, so the build profile is available in the user interface immediately, use ‐-basedir / to indicate root directory.

-f --overwrite Forces the import to overwrite existing files.

-q --quiet Non‐verbose.

--sif (export) -e <profile> --export <profile> Exports a SIF file.

-c --clean Cleans by removing passwords and IP addresses from the build profile.

-n --noclean Leaves passwords and IP addresses in the build profile.

-o <ofile> --output <ofile> Creates a SIF file named <ofile>. If an output file is not specified, the filename is derived from the profile name.

-b --basedir Base directory name for relative pathnames in the profile.

-I --include Includes a comma‐separated list of <itemtypes>. Accepted item types are: profile, package, service, core, iso, osiso, eula, logo, wintools.

Included item types default to: profile, package, service, iso, eula, logo.

-E --exclude Excludes a comma‐separated list of <itemtypes>.

-f --overwrite Overwrites an existing SIF file.

-q --quiet Non‐verbose.

--sif (list) -l <SIFfile> --list <SIFfile> Lists the contents of a SIF file.

-v --verbose Shows a long listing of the files in the specified SIF.

--sif (help) -h --help Documents options of the --sif subcommand.


106 VMware, Inc.

If you run ovfenv --dump in a VM that belongs to a powered‐on vApp, the VM properties appear in the

Property section, while the peer VM’s properties appear in an Entity section with the peer VM’s name encoded

as the oe:id value. Example 13‐1 shows the VM named cent55 with its vApp peer cent55_1:

Example 13-1. XML properties of a VM in a vApp

<Environment xmlns="[several URLs deleted here]" oe:id="cent55_1" ve:vCenterId="vm-490"> <PlatformSection> <Kind>VMware ESX</Kind> <Version>4.1.0</Version> <Vendor>VMware, Inc.</Vendor>in <Locale>en</Locale> </PlatformSection> <PropertySection> <Property oe:key="newprop" oe:value="B"/> <Property oe:key="vami.DNS.cent55" oe:value=""/> <Property oe:key="vami.DNS.cent55_1" oe:value=""/> <Property oe:key="vami.gateway.cent55" oe:value=""/> <Property oe:key="vami.gateway.cent55_1" oe:value=""/> <Property oe:key="vami.ip0.cent55" oe:value=""/> <Property oe:key="vami.ip0.cent55_1" oe:value=""/> <Property oe:key="vami.netmask0.cent55" oe:value=""/> <Property oe:key="vami.netmask0.cent55_1" oe:value=""/> <Property oe:key="vamitimezone" oe:value="US/Pacific"/> <Property oe:key="vm.ip" oe:value=""/> <Property oe:key="vm.vmname" oe:value="cent55_1"/> </PropertySection> <ve:EthernetAdapterSection> <ve:Adapter ve:mac="00:50:56:bd:05:82" ve:network="VM Network" ve:unitNumber="7"/> </ve:EthernetAdapterSection> <Entity oe:id="cent55"> <PropertySection> <Property oe:key="newprop" oe:value="B"/> <Property oe:key="vami.DNS.cent55" oe:value=""/> <Property oe:key="vami.DNS.cent55_1" oe:value=""/> <Property oe:key="vami.gateway.cent55" oe:value=""/> <Property oe:key="vami.gateway.cent55_1" oe:value=""/> <Property oe:key="vami.ip0.cent55" oe:value=""/> <Property oe:key="vami.ip0.cent55_1" oe:value=""/> <Property oe:key="vami.netmask0.cent55" oe:value=""/> <Property oe:key="vami.netmask0.cent55_1" oe:value=""/> <Property oe:key="vamitimezone" oe:value="US/Pacific"/> <Property oe:key="vm.ip" oe:value=""/> <Property oe:key="vm.vmname" oe:value="cent55"/> </PropertySection> </Entity></Environment>

Table 13-3. Examples of ovfenv Command Use

Command Example Description

ovfenv Shows all the properties in id[key]=value format

ovfenv --dump Sends the raw OVF Environment XML to standard output

ovfenv --key vm.name

ovfenv --key ’[vm.name]’Shows the local VM’s value for the property named vm.name

ovfenv --key Property_1 --id ubuntu8044

ovfenv --key ’ubuntu8044[Property_1]’Shows the value for the property named Property_1 on the VM named ubuntu8044

ovfenv --key vm.email --value [email protected]

ovfenv --key ’[vm.email][email protected]’Sets the value of the local VM’s property named vm.email to [email protected]

ovfenv --key vm.password --value ’’

ovfenv --key ’[vm.password]=’Clears the value of the local VM’s property named

vm.password

VMware, Inc. 107

14

This chapter explains the following topics:

“Importing an Existing VM Using the CLI” on page 107

“Discovering an Existing VM” on page 108

“Building with the Import Profile” on page 109

“Existing VM Capabilities and Limitations” on page 109

You can use any successful Linux VM build to create a new Linux VM. The existing VM feature can save time

when changing the application mix of an appliance, or when developing a base appliance for use as a pattern.

Importing an Existing VM Using the CLIUse the studiocli command to discover the properties of an existing VM. After discovery, studiocli creates an import profile that you can edit into a build profile using the Web console. For background on the CLI, see

“Using the Command Line” on page 103.

Prerequisites

Before you begin, note the following requirements:

You must have either a Linux‐based virtual appliance packaged as ZIP, OVF, or OVA on the local host, or

a powered‐off Linux VM on a remote provisioning engine, either ESX/ESXi or vCenter Server.

After existing VM import, you need the ISO file of a corresponding Linux OS to build the new VM.

The VMware Studio provisioning agent must be installed in the input VM for discovery.

If the input VM was built using VMware Studio with the vadk:removeAgentPackage attribute set to false (its default value), then the VM contains the provisioning agent. The Web console has this setting. On the

Build Settings page the Remove agent after provisioning check box is normally unchecked, so leave it

unchecked when building an input VM.

If the input VM was not built with VMware Studio, you must install the provisioning agent manually. The

packages vmware-studio-provagent_*_i386.rpm and vmware-studio-provagent_*_all.deb are available in /opt/vmware/www/provagent on the VMware Studio appliance. Install these packages on

the input VM before starting the discovery and import phases.

It is best if the input VM does not have an existing EULA. If it does, you must accept it on the console of

the provisioning server when the VM boots up. Alternatively you could provision with vCenter Server,

which uses a different EULA mechanism and does not request EULA acceptance on the console.

If both of these workarounds are problematic, you can edit the XML profile of the input VM, changing the

value of vadk:ShowEULA to false. You might want to set other attributes in VAMI_Section_Type to false, especially RunBootScripts. This solution works only for input VMs built with Studio 2.1 and later.

The input VM must be powered off, if it resides on a provisioning engine, as stated above.

Build From an Existing VM 14


108 VMware, Inc.

How It Works

With the import option, studiocli command calls the import.pl script, and with the name option, it calls

the import_helper.pl script. Both import scripts are in the /opt/vmware/share/build directory on the VMware Studio appliance.

One a base VM is available, building another VM with new user packages is significantly faster than building

a VM from scratch. This helps developers who want to test multiple builds with bug fixes or package changes.

Discovering an Existing VMDuring the discovery phase you tell VMware Studio where to find an existing VM. An import profile results.

To discover an existing VM and create an import profile

1 Log in as root and run studiocli with the import, name (newVM in this example), and verbose options.

studiocli --importvm --name newVM -v

2 When asked for the source VM location, type a local file pathname, or vi for remote VI (vSphere) locator.

Local pathname may be /opt/vmware/www/build/<VM>/exports/ovf/VM_OVF10.ovf, for example.

3 When asked for the remote engine type, you can type either esx or vcenter. For remote engine version,

you can accept the default 4 for vSphere 4.x.

4 When asked for host, type the IP address or DNS name of the remote provisioning engine. For port, accept

the default 443 unless it was changed.

5 Give the user name. For ESX/ESXi, accept the default root. For vCenter Server, type Administrator. Then type the user login password, twice.

6 When the CLI displays resource pool, you can accept the default.

7 If you selected VI (vSphere) locator, the script says to choose an existing VM. Press Tab twice to show the

VM list. Type the name of an existing VM from the list.

The import script reads the snapshot list and allows you to choose an old snapshot, if present. Then it asks

for the Linux OS vendor, major version, and minor version. After this, you can change the resource pool,

datastore name, and network name.

8 When asked for the transient VM name, you can use the existing VM, which probably appears in the

prompt, to avoid a left‐over transient VM.

You can also choose a different name for the transient VM, which you might want to delete later.

9 Type an output filename for the import profile, such as /root/importp, where the import script writes

the profile after discovery (/root is your home directory).

The import scripts connect to the provisioning host, configure the transient VM for provisioning, discover

the existing VM, and produce an import profile.

Afterwards, the VMware Studio Web console shows an import profile for the newly discovered VM.

Continue with the steps in “Building with the Import Profile” on page 109.

Two-Step Existing VM Discovery

If you want more control over the discovery and import phases, you can run the scripts in two steps.

To discover an existing VM then create an import profile

1 Run the import helper script to create an import profile, /root/importp2 for example.

/opt/vmware/share/build/import_helper.pl

2 Run studiocli to convert the import profile into a build profile that appears in the Web console VM List.

studiocli --importvm --name newVM2 --profile /root/importp2.xml -v

VMware, Inc. 109

Chapter 14 Build From an Existing VM

Modifying the Import Profile

You can save the import profile, /root/importp.xml in this example, for modification and later use.

Good XML editors exist, but import profile syntax is not difficult to understand, so it is best to use a text editor

that you feel comfortable with.

Building with the Import ProfileEditing a discovered VM profile differs from regular profile editing. Regular editing creates a fresh profile in

which you have to specify everything. The VM profile from an existing VM already has many items defined.

You need to supply an ISO URL and root password, but little else.

To create a new VM from an existing VM

1 Click the VMs tab.

The newly imported profile should appear in the VM Profile list.

2 Select the profile that you just imported, newVM for example.

3 Click the Edit Profile button. Proceed as usual by specifying fields in pages under the VMs tab.

You can modify most items on the Description page, including Product Name and Version.

The Hardware page imposes restrictions as listed in “Existing VM Capabilities and Limitations” on

page 109.

4 On the OS tab, provide the ISO URL of a corresponding Linux distribution, and set the root password.

The ISO URL usually looks like file:///opt/vmware/www/ISV/ISO/<distribution>.iso and the ISO MD5 is optional.

5 On the Application tab, you can remove packages on the List of packages from OS install media if you

do not want them in the new VM.

The build profiles created from an existing VM import profile do not include VMware Tools (core or X)

for you to select and enable. This is because the official VMware Tools as presented by the virtualization

platform can be installed at deployment time.

6 On the Management tab, click Enable Management CIMOM Server if you want VAMI services to appear

in the new VM. Also click Enable Management Server (GUI) if you want the Web console to appear.

7 The Output and Build Settings tabs should be filled in already from the discovery phase.

8 (Optional) Click the Validate button to verify your build profile.

9 When you are finished editing, click the Save and Build button.

You can choose to remove the provisioning agent after a build by checking Remove agent after provisioning

on the Build Settings page. This sets the vadk:removeAgentPackage attribute to true. For development and

debugging, and existing‐VM transformation, VMware recommends that you retain the provisioning agent

(vmware-studio-provagent*) in the VM. For a production virtual appliance, VMware strongly recommends

that you remove the agent.

Existing VM Capabilities and LimitationsWhen you begin with an existing VM or any qualifying Linux OS instead of with a supported OS distribution,

VMware Studio offers benefits and imposes limitations as follows:

You should not attempt concurrent builds of an existing VM, although VMware Studio does not prevent

you from doing so.

It is best for the existing VM to be a supported Linux distribution. VMware Studio makes its best effort

with any related Linux distribution using DEB or RPM packaging.

You can add and remove OS packages, application packages, and management packages.


110 VMware, Inc.

You can add new virtual hardware like hard disk, CD/DVD drive, etc. You can resize existing memory.

You cannot modify existing hard disks nor removing existing virtual hardware. Adding new hard disks

that are LVM formatted is also not supported.

You can upgrade (but not downgrade) the virtual hardware version.

You can update the virtual appliance login password (root user, for example).

When importing an external VM into Studio to be used as a base VM, Studio is currently not parsing any

LVM formatting that exists in the input VM from its discovery process. The effect is that the build profile

that Studio generates from the discovery process would not display the LVM formatting (if any) as

expected. You may see missing partition information from disks that are LVM formatted within the build

profile.

VMware, Inc. 111

Appendixes


112 VMware, Inc.

VMware, Inc. 113

A

This appendix documents the management services JavaScript API, which you can use to create a custom user

interface as a tab in the Linux virtual machine Web console. This tab is the on‐screen representation of a

management service.

“Root Object” on page 113

“VAMI Container” on page 113

“VAMI Container Callbacks” on page 114

“VAMI I/O” on page 115

“VAMI Log” on page 116

“Managing Builds” on page 117

As shown in “Creating a Management Service” on page 63, a UI can be specified in the view.xml both as a <Content type="html"> and as <Content type=”url”>. This JavaScript API can be used in both cases.

Root ObjectThe root object vami has over a dozen methods to navigate within a Web container, communicate with the

lighttpd Web server, and log information for debugging purposes. To obtain the vami root object within

JavaScript, call the parent:

var vami = parent.vami;

VAMI ContainerThe following functions can be called on the root vami object.

vami.container.navigate

Requests that the container navigate to a page. Returns true if the container is able to navigate.

boolean navigate(String token)

Parameter:

token – A string representing the destination page, in the form ServiceName.PageName where PageName is optional. If PageName is not present, it goes to the first page in the Service.

Example:

vami.container.navigate('network.Status');

vami.container.logout

Logs out the current user.

Management Services Web API A


114 VMware, Inc.

void logout()

vami.container.newHistoryItem

Adds a new browser history item.

void newHistoryItem(String historyToken)

Parameter:

historyToken – The token assoicated with the history item.

Example to record a history change:

vami.container.newHistoryItem('myservice.InternalPage');

vami.container.isLogin

Checks to see if the user is logged in. Returns true if the user is still logged in.

public boolean isLogin()

vami.container.getUser

Gets the name of user who is currently logged in. Returns the user name of the current login.

public String getUser()

vami.container.getSessionID

Returns the current session ID, which is used for authentication with PAM or to communicate with sfcbd.

public String getSessionID()

Example to authenticate a user on the server side using Python:

# import required librariesimport syssys.path.append('/opt/vmware/lib/python/site-packages/')import pywbem# returns true if we are able to authenticatedef authenticate(user, sessionid):

try:# connect to cimom with username and sessionid, make CIM callcliconn = pywbem.WBEMConnection('http://localhost:5488', (user, sessionid))cliconn.EnumerateInstanceNames('VAMI_ComputerSystem')return True

except Exception, e:return False

VAMI Container CallbacksVAMI Web container provides callbacks for services to register and get notified of various navigational events.

vami.container.registerOnShowCallback

Registers a callback function with the container for execution when the Service is displayed. The callback

function you pass will then receive the token for the current page.

public void registerOnShowCallback(JavaScriptObject callback)

Parameter:

callback – Function that gets executed when the Service is displayed. This function will receive the token for

the current page.

Example to register a callback function:

function myOnShow(token){

VMware, Inc. 115

Appendix A Management Services Web API

alert(token);vami.container.registerOnShowCallback(myOnShow);

vami.container.registerOnHideCallback

Registers a callback function with the container for execution when the Service is hidden and the user moves

to another Service. The callback function you pass will then receive the token for the page to be navigated.

public void registerOnHideCallback(JavaScriptObject callback)

Parameter:

callback – Function that gets executed when the Service is hidden. This function will receive the token for

the pending page to where the user is navigating.


function myOnHide(pendingToken){return confirm(pendingToken);

}vami.container.registerOnHideCallback(myOnHide);

vami.container.registerOnNavigateCallback

Registers a callback function with the container for execution when the container navigates to the current

Service. The callback function you pass will then receive the token to indicate navigation.

public void registerOnNavigateCallback(JavaScriptObject callback)

Parameter:

callback – Function that gets executed when the Service is hidden. This function will receive the token for

the current page. Callback function should be in this format:

functionName(token);


function myOnNavigate(pendingToken){alert(token);

}vami.container.registerOnNavigateCallback(myOnNavigate);

VAMI I/OThe VAMI Web container provides a vami.io object to communicate with the lighttpd Web server.

vami.io.httpGet

Make an HTTP GET request for the provided URL, and feed the result to the callback function. Because of

Same Origin Policy (SOP) restrictions, this API cannot make calls to any other server other than the server from

which this page is loaded.

public void httpGet(boolean authenticate, boolean blocking, String description, String url, JavaScriptObject callback)

Parameters:

authenticate – True if you want to use HTTP basic access authentication on the currently logged in

username and password. See the Wikipedia article about Basic Access Authentication.

blocking – True to indicate to the container that this is a blocking request.

description – Description of the request, to be shown in the user interface.

url – Relative or full HTTP URL for this request.

callback – JavaScript callback function that takes a string as its argument. The returned content from the

request is passed to this callback function.


116 VMware, Inc.

Example to request a file:

vami.io.httpGet(false, false, 'Get XML file', '/VAMI.xml', alert);

Example to request a JavaScript Object Notation (JSON) object and parse that object:

function evaluateJSON(json){eval(json);

}vami.io.httpGet(false,false,'Get JSON Object','/RESTInterface',evaluateJSON);

vami.io.httpPost

Make an HTTP POST request for the provided URL, and feed the result to the callback function. Because of

Same Origin Policy (SOP) restrictions, this API cannot make calls to any other server other than the server from

which this page is loaded.

httpPost public void httpPost(boolean authenticate, boolean blocking, String description, String url, String content, JavaScriptObject callback)

Parameters:

authenticate – True if you want to use HTTP basic access authentication on the currently logged in

username and password. See the Wikipedia article about Basic Access Authentication.

blocking – True to indicate to the container that this is a blocking request.

description – Description of the request, to be shown in the user interface.

url – Relative or full HTTP URL for this request.

content – Content to post for the URL, usually for HTTP GET request this is part of the request URL.

callback – JavaScript callback function that takes a string as its argument. The returned content from the

request is passed to this callback function.

Example to request a call to the sfcb:

var cimXML; //fill cimXML with the CIM XML that you want to post to CIMOMvami.io.httpPost(true,false,'Making CIMOM Call','/cimom', cimXML, evaluateJSON);

VAMI LogTo enable logging for a virtual machine Web console, use <webconsoleurl>?log=info&logwindow=true. This shows a small visible window that displays all messages that are logged using vami.log object. Other options for the log parameter are warn and error.

vami.log.info

Logs an informational message.

public void info(String message, JavaScriptException exception)

Parameters:

message – Message string to log.

exception – JavaScript exception. Optional.

vami.log.warn

Logs a warning message.

public void warn(String message, JavaScriptException exception)

Parameters:



VMware, Inc. 117

Appendix A Management Services Web API

vami.log.error

Logs an error message.

public void error(String message, JavaScriptException exception)

Parameters:



Managing BuildsFor every build of a virtual machine, VMware Studio maintains a build instance number and the logs for that

build. For example, build instance 1 stores logs in the following directory:

/opt/vmware/www/build/1/status/

This directory contains three important log files for each build:

verbose.log – High level information of the build process.

postinstall.log – Information about the build of the virtual machine including package installation.

debug.log – Detailed information about the build including ISO management, network communications,

and provisioning information.

Build logs are accessible using the Studio Web console to troubleshoot build failures.

Discovery Reports

The studiocli command generates several report files during VM discovery, which are available in the

following directory:

/opt/vmware/www/build/<VM-name>.<instance>/discover

Old Builds

VMware Studio stores and logs all the virtual machines that it builds. Unneeded build instances should be

removed and older build instances should be archived away to recover free disk space for VMware Studio.

You can obtain a list of all builds by running this command:

studiocli --buildstatus

You can obtain information about a specific build by specifying its profile or instance number:

studiocli --buildstatus --profile myVirtualMachinestudiocli --buildstatus --instance profileABC.7

To delete just one instance of a build, run the following command:

studiocli --deletebuild --instance profileABC.7 --verbose


118 VMware, Inc.

VMware, Inc. 119

B

Virtual appliances built by VMware Studio can be configured to connect to both IPv4 and IPv6 networks, if the

underlying operating system supports IPv6. If required, the ISV user can enable only the IPv4 option.This

appendix discusses the following topics:

“Supporting IPv6 in Virtual Appliances” on page 119

“About IPv6 Support” on page 120

The first major section summarizes the developer and administrator actions for enabling IPv6 and DHCPv6 in

virtual appliances. The remaining sections discuss the IPv6 design choices made for VMware Studio.

Supporting IPv6 in Virtual AppliancesWhen IPv6 is enabled, a network adapter can have both IPv6 and IPv4 on the same network. Usually IPv6 is

not added with a separate network adapter. VMware Studio follows this industry‐wide standard practice.

As described in “Network Configuration in the Web Console” on page 25, you can configure IPv6 networking

when a virtual appliance is running and connected to an IPv4 network. After you build virtual appliances that

contain the VAMI component, end users can set IPv6 networking using a similar procedure.

The Auto IPv6 address is derived from the network adapter’s MAC address. A machine on an IPv6 network

performs autodiscovery of neighboring machines and devices. The Auto address is part of the IPv6 protocol.

VMware Studio does not attempt disable the Auto IPv6 address on any operating system or kernel version.

IPv6 in Virtual Appliances

If IPv6 is supported by the underlying operating system, it will be available in virtual appliances built from it.

The VMs > Build Settings page has a drop‐down menu under Network Settings, where you can choose

DHCP or Static network addressing for the transitory virtual machine during provisioning. This setting has

no effect on the resulting virtual appliance.

On the VMs > Output page, the OVF Properties for IP assignment can help control DHCP or Static network

addressing for virtual appliances that are deployed through vCenter Server. The administrator can accept the

OVF network choices for a virtual appliance, or change them, and possibly set host name and IP address.

Changing the IPv6 Configuration

After VMware Studio builds a virtual appliance containing the VAMI component, end users of the appliance,

after deployment, can reconfigure network settings on the Network > Address page.

Virtual appliances built by VMware Studio report stateless address auto‐configuration (SLAAC) addresses but

do not manage their configuration. SLAAC is the mechanism that creates the Auto IPv6 address mentioned

above. Use of SLAAC might not be approved network policy in some organizations.

IPv6 Networks and Virtual Appliances B


120 VMware, Inc.

End users can add an additional Static IPv6 or DHCPv6 address to the appliance. Unlike IPv4, IPv6 permits

multiple addresses assigned to an interface. The Static IPv6 or DHCPv6 address that gets assigned may differ

from the SLAAC Auto IPv6 address.

For more information, see the User’s Guide to Deploying vApps and Virtual Appliances.

About IPv6 SupportThe IPv6 support in VMware Studio 2.5.0.0 and later unifies IPv4 and IPv6 network configurations rather than

adding a new network configuration to a virtual appliance.

An administrator new to IPv6 might think that adding an IPv6 network to VM is like adding a second IPv4

network to the VM. However, adding an IPv6 network to a pre‐existing network interface that is already

configured for IPv4 shows it is possible. The IPv4 subnet and the IPv6 subnet are intended to be roughly

similar, although the IPv6 subnet prefix (similar the IPv4 netmask) is generally fixed at 64 bits.

For compatibility and ease of administration, VMware Studio takes the approach of unifying the network

interface configuration across both the IPv4 and IPv6 networks. Sophisticated routing configurations and

network policies can be handled by the gateway. Specifying the IPv6 gateway is optional because the gateway

can be autodiscovered. (An IPv6 gateway does not need to be a routable address.)

DHCPv6 Availability

In the following cases, DHCPv6 is not available in the interface:

When a virtual appliance is based on an OS that was made available to Studio with the --newos option of studiocli. See “Retrieve OVF Properties” on page 105.

With an OS that lacks a DHCPv6 client. User has to install the DHCPv6 client on CentOS and SLES. Older

versions of Ubuntu, including Ubuntu 8.04, lack a supported DHCPv6 client, but one is available in the

“universe” community‐maintained open software source.

Not all vendors fully test their DHCPv6 configurations, and standard test suites are not yet fully developed.

IP Configurations

With IPv4, there are two methods to configure addresses:

User supplied static IPv4

Server supplied DHCPv4

With IPv6, there are three methods to configure addresses:

User supplied static IPv6

Server supplied DHCPv6

Network autoconfigured as Auto

About SLAAC

The purpose of SLAAC is to embed dynamic configuration inside IPv6 and not require a separate server to

provide dynamic networking configurations. SLAAC is a feature of the IPv6 network and IPv6 compliance

relies on its functioning. At this time, industry trends are not clear. SLAAC may or may not replace DHCPv6.

With SLAAC enabled, passing the “IPv6 Logo Phase 2” network tests requires reconfiguration of certain

options for different test phases. Virtual machines may opt out of using SLAAC, but this is best handled with

router configuration rather than by altering the virtual machine or guest operating system. VMware Studio

does not disable the acquisition of SLAAC addresses for virtual machines. It always uses SLAAC addresses

and reports on their existence.

VMware, Inc. 121

Appendix B IPv6 Networks and Virtual Appliances

Name Service

When the auto‐configuration protocol was defined, DNS servers were not included as part of the information

provided to entities on the network.

With SLAAC today, an appliance receives dynamic addressing and subnetwork information, but receives no

information about DNS name servers. Administrators must configure static DNS in this case.

This means that DHCP is required for IPv6 dynamic configurations to attain familiar IPv4 behaviors. However

DHCPv6 server deployments are not as common as DHCPv4 server deployments.

Recently, an RFC was made to amend how SLAAC works to include DNS servers. It is unknown how the

various operating system vendors will eventually decide to handle this.

Subnetworks and Routing

With IPv4, there are four items in a configuration:

Address

Netmask

Broadcast

Gateway

With IPv6, there are two items in a configuration:

Address

Prefix, similar to the classless inter‐domain routing (CIDR) shorthand for netmask

Gateway (optional)

Avoiding Potential DNS Conflicts

From the point of view of a virtual appliance, although technically possible, it would be confusing to have

different DNS behaviors based on which IP version is used. Ultimately, like‐hostname requests from DNS

should result in like‐addresses regardless of whether the results are IPv4 or IPv6 addresses. Otherwise, the

virtual appliance would have to function as if it were on different networks.

DHCPv6 must write name server information that it receives into /etc/resolv.conf, DHCPv4 must do the

same. The DHCPv4 and the DHCPv6 clients operate independently from each other (even if they come from

the same source code) and neither has a notion of priority.

DHCP clients have traditionally overwritten the contents of /etc/resolv.conf. Therefore a the end user of a virtual appliance must trust the network administrator to make sure that the DNS services from the DHCPv6

server do not conflict with those of the DHCPv4 server.

Existing DNS servers can be configured to return IPv6 addresses for name service requests. This reduces the

potential problem, noted above, where both DHCPv4 and DHCPv6 clients clobber nameserver configurations.

Automatic Name Service

VMware Studio treats SLAAC configurations as name‐server‐less, and asks users to supply a name server.

Because SLAAC is part of the operating system kernel and not a server‐client operation, it is not clear how the

kernel alters name service configuration, when or if the SLAAC amendments are operational.

Remember, the common case will be DHCPv4 and SLAAC, so name service usually should be automatic.

Conclusion

Adding IPv6 support to a virtual appliance is conceptually straightforward, but the details surrounding IPv6

required that VMware Studio should unify the IPv4 and IPv6 configurations.


122 VMware, Inc.

VMware, Inc. 123

C

This appendix contains the following sections:

“Installing SSH on Windows Workstation” on page 123.

“Checking Veracity of an SSL Certificate or SSH Key” on page 124

Installing SSH on Windows WorkstationVMware Studio requires the secure shell (SSH) protocol to communicate with some provisioning platforms,

including VMware Workstation. With other provisioning platforms, VMware Studio uses HTTPS instead.

When Workstation runs on a Linux host, the SSH protocol is usually available by default. When Workstation

runs on Windows, you must install OpenSSH as follows.

To install the SSH daemon on a Windows system

1 Download the OpenSSH 4.2p1‐1 for Windows Binary Installer from http://sshwindows.webheat.co.uk/.

2 Run the installer, setupssh.exe.

3 After installation, create a working directory for provisioning virtual machines, for example:

mkdir C:\vmware_studio-tmp

4 Select a username and password to use in the script below.

5 The following script uses the net user command to create a user named vmware_studiouser with

password VMware. Later it uses the cacls command to control ACLs for the C:\vmware_studio-tmp directory you just created. Either create a batch script containing the following commands, or run these

commands sequentially in a command prompt window:

net user vmware_studiouser VMware /addC:cd \"Documents and Settings"mkdir vmware_studiouser\.sshcacls vmware_studiouser /T /P everyone:Fcd \cacls vmware_studio-tmp /G everyone:Fcd \Program Files\OpenSSH\binmkgroup -l > ..\etc\groupmkpasswd -l > ..\etc\passwd

6 Launch the OpenSSH daemon by running the net start command:

net start opensshd

Security with SSH and SSL C

NOTE This particular version of OpenSSH works well on Windows XP. If you have a different version of

Windows, you should consider installing a recent version of Cygwin and its OpenSSH option.

NOTE c:\vmware_studio-tmp translates to /cygdrive/c/vmware_studio-tmp File Transfer Path.


124 VMware, Inc.

7 Disable any firewall, or preferably, create an exception in the Windows system firewall to avoid blocking

the SSH connection with VMware Studio (both TCP and UDP protocols on port 22).

Checking Veracity of an SSL Certificate or SSH KeyThis procedure helps you verify that the host to which you are connecting is indeed the host you intended.

To display and validate SSL and SSH fingerprints

1 From the main VAMI screen on local console, make a note of the URL displayed on the [Web] line, and select Login.

2 Log in as root using the password you selected during first boot of the VMware Studio appliance.

3 Run the following command to display the SHA‐1 fingerprint of the x.509v3 (SSL) certificate for the

VMware Studio HTTP server:

/usr/bin/openssl x509 -fingerprint -sha1 -noout -in /opt/vmware/etc/lighttpd/server.pem

Summary of options:

x509 – Use x.509 certificate mode (no leading dash).

-fingerprint – Display fingerprint.

-sha1 – Display SHA‐1 hash value for fingerprint.

-noout – Do not output the entire certificate.

‐in <infile> – Use the specified file as the source file.

4 Run the following command to display the fingerprint of the SSH2 or RSA key for the SSH server:

/usr/bin/ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key.pub

Summary of options:

-l – List (show) fingerprint.

-f <infile> ‐‐ Use the specified file as the source file.

5 Using your choice of supported Web browser, go to the URL you noted down in Step 1.

The HTTP listener on port 80/tcp redirects to an HTTPS (HTTP with SSL) listener on port 5480/tcp.

Awarning appears, explaining that the SSL Certificate could not be validated using existing information.

6 Fetch the certificate, view the certificate summary, locate the SHA‐1 fingerprint, and compare it to the

SHA‐1 fingerprint you generated in Step 3.

7 If the SHA‐1 fingerprints match, confirm the security exception. You can choose to store it permanently.

If the SHA‐1 fingerprints do not match, you might be experiencing a man‐in‐the‐middle security attack.

If you confirm the security exception, your Web browser proceeds to the VMware Studio login screen.

8 To verify the fingerprint of the SSH2 or RSA key for the SSH server, choose either “To confirm with

Interactive SSH” on page 124, or “To confirm with SCP or SFTP” on page 125.

To confirm with Interactive SSH

1 Using your choice of SSH client (for example PuTTY 0.60), or the ssh command on Linux, connect to the

IP address within the URL that you noted down in Step 1. The SSH client prompts you to accept or reject

the key presented (in the case of PuTTY, a 2048 bit RSA key over SSH v2).

2 Compare this fingerprint to the SSH2 or RSA fingerprint you generated in Step 4.

3 If the fingerprints match, accept a trust relationship. You can choose to cache your decision permanently,

rather than for this SSH session only.

4 The SSH client proceeds with session initiation. After the VMware Studio message, a root shell appears.

VMware, Inc. 125

Appendix C Security with SSH and SSL

To confirm with SCP or SFTP

1 Using your choice of SCP client (for example WinSCP 4.x), or the scp command on Linux, connect to the

IP address within the URL that you noted down in Step 1. The SCP client prompts you to accept or reject

the key presented (in the case of WinSCP, a 2048 bit RSA key over SSH v2).

2 Compare this fingerprint to the SSH2 or RSA fingerprint you generated in Step 4.

3 If the fingerprints match, accept a trust relationship. You can choose to cache your decision permanently,

rather than for this SCP session only.

4 The SCP client proceeds with session initiation.


126 VMware, Inc.

VMware, Inc. 127

D

This appendix can help you edit XML build profiles. It contains the following sections:

“Introduction” on page 127

“Structure of VM XML Build Profiles” on page 127

“Useful Attributes Not Displayed in the VMware Studio Web Console” on page 136

“Customizing the Footer in the Web Console” on page 137

“Creating Virtual Disks, Partitions, and Virtual Devices” on page 137

“Logical Volume Management in Build Profile” on page 139

“Signing OVF Files” on page 139

“Unmounting CDROM or ISO After a Build” on page 140

“Resource Allocation Setting Data” on page 140

“Structure of vApp XML Build Profiles” on page 141

IntroductionVMware Studio creates a build profile that defines a virtual machine.

The XML schemas for the build profiles are located in the /opt/vmware/etc/build/schemas directory inside VMware Studio. It is never necessary or required to look at these schemas for the construction of build

profiles. VMware recommends that you use the VMware Studio Web console to create build profiles. Once

created, you can edit the build profile and build or rebuild the VM or vApp.

The VMware Studio Web console saves build profiles in the following locations for a VM and a vApp:

/opt/vmware/var/lib/build/profiles/<VMprofileName>.xml/opt/vmware/var/lib/build/vapp_profiles/<vAppProfileName>.xml

VMware Studio includes preconfigured build profile templates, located in the following directories:

/opt/vmware/etc/build/templates/<OS>/<release>/<version>/build_profile.xml/opt/vmware/etc/build/vapp_template/vapp_template.xml

Build profiles conform to an early version of the OVF 0.9 draft specifications. For more information about OVF,

see http://www.vmware.com/appliances/learn/ovf.html.

Structure of VM XML Build ProfilesThe sections of the build profile correspond to sections in the VMware Studio build interface.

Table D‐1, “VM Build Profile XML Configuration Properties,” on page 128 describes the configuration

properties in the build profile XML file.

Editing XML Build Profiles D

http://www.vmware.com/appliances/learn/ovf.html


128 VMware, Inc.

Table D-1. VM Build Profile XML Configuration Properties

Property Description

Information The ProductSection contains ISV branding information for the VM.

Product Name This name is visible to users on the text welcome screen and on the Web console after deployment of the VM.

//ovf:Envelope/Section[@xsi:type='ovf:ProductSection_Type']/Product

Vendor Name Name of the vendor. Important when shipping a virtual appliance.

//ovf:Envelope/Section[@xsi:type='ovf:ProductSection_Type']/Vendor

Version VMware Studio uses the version of the virtual machine to track updates. It may be in n.n.n.n format, where ‘n’ is a number between 0 and 65535.

//ovf:Envelope/Section[@xsi:type='ovf:ProductSection_Type']/Version

Full Version Free format text string used to display the version information of the virtual machine.

//ovf:Envelope/Section[@xsi:type='ovf:ProductSection_Type']/FullVersion

Product URL URL to the company’s Web site which provides information about the product.

//ovf:Envelope/Section[@xsi:type='ovf:ProductSection_Type']/ProductUrl

Vendor URL URL to the your company’s Web site.

//ovf:Envelope/Section[@xsi:type='ovf:ProductSection_Type']/VendorUrl

Application URL URL to the main application Web page. Instead of a host name in the http URL, you can use the variable string ${app.ip}, which resolves to the IP address of the VM.

//ovf:Envelope/Section[@xsi:type='ovf:ProductSection_Type']/AppUrl

Category Usually Application.

//ovf:Envelope/Section[@xsi:type='ovf:ProductSection_Type']/Category

Description Description of the functionality the virtual machine provides. It is displayed when the virtual machine is imported into ESXi as an OVF.

//ovf:Envelope/Section[@xsi:type='ovf:AnnotationSection_Type']/Annotation

EULA Text End‐user licensing agreements for the VM. The user must accept all EULAs before using the VM. When deploying on vSphere, the vSphere Client handles ovf:EulaSection_Type acceptance.

//ovf:Envelope/Section[@xsi:type='ovf:EulaSection_Type']/License

You can add multiple EULA texts by copying the <Section> element containing EulaSection_Type and placing additional EULA texts in repeated <Section> elements. You can also specify EULAs in different languages by changing the xml:lang= setting, which selects EULA by prevailing locale.

<Section xsi:type="ovf:EulaSection_Type" xml:lang="en"> <Info>End User License Agreement</Info> <License>English EULA text here</License> </Section> <Section xsi:type="ovf:EulaSection_Type" xml:lang="fr"> <Info>Accord de licence d'utilisateur</Info> <License>French EULA text here</License> </Section>

In VMware Studio 2.1 and later you can also specify a filename or filenames containing the EULA text, possibly in different languages, selected according to the prevailing locale (see EULA Location below).

EULA Location Specifies the location of a EULA file. May be repeated for multiple EULA files. Although discussed here, this appears in BuildSection_Type. You can specify EULAs in different languages by changing the xml:lang= setting, which selects EULA by prevailing locale.

<vadk:EULAlocation xml:lang="en">/opt/eula_en.txt</vadk:EULAlocation><vadk:EULAlocation xml:lang="fr">/opt/eula_fr.txt</vadk:EULAlocation>

If you define the EULA text in EulaSection_Type (above) and also in a EULAlocation file, all EULAs are prompted‐for during deployment and first boot, except when the vSphere Client handles EULA acceptance. The display order of EULAlocation and EulaSection_Type texts is indeterminate.

More Information The ExtendedProductSection contains additional ISV branding items.

Vendor UUID Universally Unique Identifier for the ISV. Mandatory for VMware vCenter Update Manager. For details, see “Supporting Central Updates with VMware vCenter Update Manager” on page 74.

//ovf:Envelope/Section[@xsi:type='vadk:ExtendedProductSection_Type']/vadk:VendorUUID

VMware, Inc. 129

Appendix D Editing XML Build Profiles

Product RID Repository Identifier for the virtual appliance. Mandatory for VMware vCenter Update Manager. For details, see “Supporting Central Updates with VMware vCenter Update Manager” on page 74.

//ovf:Envelope/Section[@xsi:type='vadk:ExtendedProductSection_Type']/vadk:ProductRID

Application Link Label Label provided in this field is shown in the Web console for this virtual machine. This label points to the URL provided in Application Link URL field.

//ovf:Envelope/Section[@xsi:type='vadk:ExtendedProductSection_Type']/vadk:AppUrlName

Logo Path Icon displayed in the Web console for the virtual machine. Specify the location of an image file that you have copied into a directory in VMware Studio.

//ovf:Envelope/Section[@xsi:type='vadk:ExtendedProductSection_Type']/vadk:Logo

Logo URL URL to your company’s Web site.

//ovf:Envelope/Section[@xsi:type='vadk:ExtendedProductSection_Type']/vadk:LogoUrl

Welcome Text Welcome text for the virtual machine shown in the welcome screen. The welcome text must be 16 lines or less, with a maximum of 79 characters in each line. Any lines or characters greater than these limits will not display in the virtual machine console.

//ovf:Envelope/Section[@xsi:type='vadk:ExtendedProductSection_Type']/vadk:WelcomeText

SSL Certificate The SSLCertificateSection provides details about the appliance’s SSL certificate.

Common Name Server certificates are issued to a common name. In most cases, this is the full DNS name used when navigating a Web site.

//ovf:Envelope/Section[@xsi:type='vadk:SSLCertificateSection_Type']/vadk:CommonName

Organization Legal name of your organization. It is used to sign the certificate.

//ovf:Envelope/Section[@xsi:type='vadk:SSLCertificateSection_Type']/vadk:OrganizationName

Organizational Unit Department or section of your organization. This information is used in the creation of the certificate.

//ovf:Envelope/Section[@xsi:type='vadk:SSLCertificateSection_Type']/vadk:OrganizationalUnitName

Country Code Two letter country code representing the country in which the organization or unit is based. This information is used in the creation of the certificate.

//ovf:Envelope/Section[@xsi:type='vadk:SSLCertificateSection_Type']/vadk:CountryName

Management The VAMISection describes the management services in this VM.

Initialization Script Location of the virtual appliance OS initialization script, vaos_init.sh by default.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:InitScript

Show EULA Whether or not to display the EULA at first boot, true or false.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:ShowEULA

Set Hostname Whether or not to set the hostname, true or false.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:SetHostname

Set Network Whether or not to set the network, true or false.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:SetNetwork

Create SSH Keys Whether or not to create SSH keys, true or false.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:CreateSSHKeys

Run Boot Scripts Whether or not to run boot scripts, true or false.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:RunBootScripts

Enable Console Login Whether or not to enable console (TTY) login, true or false.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:LoginTTY

Table D-1. VM Build Profile XML Configuration Properties (Continued)



130 VMware, Inc.

Enable VAMI Services Whether or not to enable management services, true or false.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:ManagementSrv

Enable Management GUI Whether or not to enable the Web console UI, true or false.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:ManagementGUI

Service Name Name of the service. These are either VAMI services or services created and added by the user.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:Service/@vadk:name

Service Version Specifies the version of the added services.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:Service/@vadk:version

Service TabOrder Order in which the added services appear in the generated VM.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:Service/@vadk:tabOrder

Web Server Port Configurable port number for the lighthttpd Web server. This is the port number to access your VM from the Web browser.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:WebServer/@vadk:httpsPort

Footer and Copyright Left side footer (FooterLeft) and copyright in the middle section of the footer (FooterCopyright).

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:Service/@vadk:ViewCustomization

Install VMware Tools Whether to install VMware Tools core package and X11 window system package.

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:VMToolsCore/@vadk:pkgsDir

//ovf:Envelope/Section[@xsi:type='vadk:VAMISection_Type']/vadk:VMToolsX/@vadk:pkgsDir

Application The ApplicationSection describes package content and output format.

VM Name Name of the virtual machine file. This name is visible to users when they download the virtual machine ZIP or OVF package.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:VMXFilename

Distribution Format Use OVF format to deploy on VMware vSphere. Use ZIP to deploy on VMware hosted products.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:DistributionFormat/@vadk:format

OVF Filename Name of the vApp OVF or OVA output file.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:DistributionFormat/@vadk:filename

ZIP Archive Directory Directory under which all files related to the VM should appear in the generated archive. ZIP only.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:DistributionFormat/@vadk:directory

Post Output Creation Signing Script

If enabled, this script generates a self‐signed certificate or could install an SSL certificate if available. The script applies to the distribution format of its containing section.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:PostOutputCreation/@vadk:script

Application Packages List of repository URLs where application packages are available. You can copy application packages onto the VMware Studio appliance (/opt directory on the first line), which is made available at the following URL (second line):

/opt/vmware/www/ISV/appliancePackages

http://[VADK.localIP]/ISV/appliancePackages

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:ApplicationPackages



VMware, Inc. 131


OS Package List The packages added by the user through the UI are added in the Application Section. These are the additional OS packages required by the ISV’s application.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:OSPackages

Packages to Remove For footprint reduction, the packages to be removed from the standard OS distribution.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:PackagesToRemove

First Boot Script Shell script that runs when the virtual machine boots up for the first time.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:BootActions/vadk:FirstBoot

Subsequent Boot Script Shell script that runs when the virtual machine boots up each time except for the first time.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:BootActions/vadk:SubsequentBoot

Root Password Password for the administrative user account for the virtual machine.

//ovf:Envelope/Section[@xsi:type='vadk:ApplicationSection_Type']/vadk:Users/vadk:User[@vadk:username='root']/@vadk:password

OVF IP Assignment The IpAssignmentSection describes how OVF controls IP assignment.

DHCP Enable the option of using the DHCP server for configuring networking of the VM.

//ovf:Envelope/Section[@xsi:type='vadk:IpAssignmentSection_Type']/vmw:IpAssignmentSection[@vmw:schemes=”dhcp”]

OVF Environment Enable the option of using a fixed or a transient IP address for the VM.

//ovf:Envelope/Section[@xsi:type='vadk:IpAssignmentSection_Type']/vmw:IpAssignmentSection[@vmw:schemes=”ovfenv”]

OVF Property The PropertySection sets OVF properties.

Key Key to the OVF Property.

//ovf:Envelope/Section[@xsi:type='vadk:PropertySection_Type']/Property/@ovf:key

Label Label for the OVF property.

//ovf:Envelope/Section[@xsi:type='vadk:PropertySection_Type']/Property/Label

Description Description for the OVF property.

//ovf:Envelope/Section[@xsi:type='vadk:PropertySection_Type']/Property/Description

Type Type of the OVF property

//ovf:Envelope/Section[@xsi:type='vadk:PropertySection_Type']/Property/ovf:type

Default Value Value of the OVF property according to the type.

//ovf:Envelope/Section[@xsi:type='vadk:PropertySection_Type']/Property/@ovf:value

User Configurable Whether to prompt user to allow changing property.

//ovf:Envelope/Section[@xsi:type='vadk:PropertySection_Type']/Property/@ovf:userConfigurable

OVF Qualifiers OVF‐standard type qualifiers.

//ovf:Envelope/Section[@xsi:type='vadk:PropertySection_Type']/Property/@ovf:qualifiers

VMW Qualifiers VMware‐specific type qualifiers.

//ovf:Envelope/Section[@xsi:type='vadk:PropertySection_Type']/Property/@vmw:qualifiers

Update Repository If the update service is enabled, UpdateSection describes setup of the update repository.

Update Repository URL URL to the update repository. This URL is embedded in the generated virtual machine and if the VM is shipped as virtual appliance, it is used to check for and install available updates. If the URL is changed in a subsequent version, the ISV should inform end‐users, in the update description, to reboot the virtual appliance so that SFCB can process the new URL.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:Repository/@vadk:url




132 VMware, Inc.

Username (optional) Username used to authenticate the Web server at the URL for the update repository.

To comply with licensing restrictions, this field is required for updating any virtual appliance based on the Red Hat Enterprise Linux (RHEL) operating system.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:Repository/@vadk:username

Password (optional) Password used to authenticate the Web server at the URL for the update repository. In order to comply with licensing restrictions, this field is required to update any virtual appliance based on the Red Hat Enterprise Linux (RHEL) operating system. Password format follows.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:Repository/@vadk:password

File Transfer Protocol Protocol used to publish software updates to the Web server which serves as an update repository.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:RepositoryStagingServer/@vadk:fileProto

File Transfer Hostname Hostname of the host running the Web server which serves as an update repository.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:RepositoryStagingServer/@vadk:hostname

File Transfer Username This is the username used by VMware Studio to copy files using scp protocol to the repository staging server. It can be different from what the virtual machines use to download updates via http.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:RepositoryStagingServer/@vadk:fileLogin

File Transfer Password This is the password used by VMware Studio to copy files using scp protocol to the repository staging server. It can be different from what the virtual machines use to download updates via http.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:RepositoryStagingServer/@vadk:filePassword

File Transfer Path Path used for publishing virtual appliance updates to the update repository. If the virtual appliance has to find any updates, this path should translate to the update repository URL.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:RepositoryStagingServer/@vadk:filePath

Update Description Update information presented here is displayed in the Web console of the virtual machine when the update becomes available.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:Info

Update ArchiveExport File

Filename of the update archive ZIP file that will be exported to the build instances directory.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:RepositoryExport/@vadk:filename

Pre Install Shell Script Script to be executed before the update.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:PreInstallShellScript

Pre Install Shell Script Script to be executed after the update.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:PostInstallShellScript

Digitally Signed Update This section contains three scripts. The first signs the update with a temporary or permanent certificate. The second gets the public key for signing and verification. The third validates the update certificate.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:DigitalSignature/vadk:Script/@vadk:name=”sign”

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:DigitalSignature/vadk:Script/@vadk:name=”pubkey”

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:DigitalSignature/vadk:Script/@vadk:name=”validate”

Update Information This section tracks updates, including the version when introduced, to avoid unnecessary updating.

//ovf:Envelope/Section[@xsi:type='vadk:UpdateSection_Type']/vadk:UpdateInfoList/

(fields include introduced-version, category, severity, affected-versions, description, reference-type, reference-id, reference-url)



VMware, Inc. 133


CIM Operating System The OperatingSystemSection shows the guest operating system as defined by CIM.

Operating System Name of the operating system.

//ovf:Envelope/Section[@xsi:type='vadk:OperatingSystemSection_Type']/vadk:RepositoryExport/@vadk:description

OS Information Information about the operating system.

//ovf:Envelope/Section[@xsi:type='vadk:OperatingSystemSection_Type']/vadk:RepositoryExport/@vadk:info

Virtual Hardware The VirtualHardwareSection describes virtual hardware configuration.

CAUTION VMware strongly recommends that you use the VMware Studio Web console to edit the virtual hardware settings, because invalid configurations can cause build failure. See “Creating Virtual Disks, Partitions, and Virtual Devices” on page 137.

In the following XML items, <rasd:InstanceId> should be sequential starting with number one (1) and unique for every new resource.

CPUs The number of virtual processors to be configured for this virtual machine.

IMPORTANT This number must be less than or equal to the number of CPUs in the provisioning platform used to create the virtual machine. If the machine on which the provisioning platform runs is incapable of booting a virtual machine with more than one CPU, then you can specify only one CPU in the build profile.

//ovf:Envelope/Section[@xsi:type='ovf:VirtualHardwareSection_Type']/

Item[rasd:ResourceType = ‘3’] - defines the CPUs

Item/rasd:VirtualQuantity - defines the number of CPUs

Memory (MB) Amount of memory (RAM) in megabytes (MB) allocated to this virtual machine in 4MB increments.

//ovf:Envelope/Section[@xsi:type='ovf:VirtualHardwareSection_Type']/

Item[rasd:ResourceType = ‘4’] - defines the memory (RAM)

Item/rasd:VirtualQuantity - defines the amount of memory

Virtual Hard Disk There can be a maximum of 4 partitions on each virtual disk. However, in most cases, one full size partition should be sufficient, since there is a maximum of 60 disks supported.

It is recommended that you use the VMware Studio Web console to add disks and partitions. This section is complicated and has many interdependencies within the build profile XML. For more information, see “Creating Virtual Disks, Partitions, and Virtual Devices” on page 137.

Operating System The JEOSSection describes the just‐enough operating system for the VM.

OS Distribution Indicates the name of the OS for your virtual machine.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:Distribution

Boot Parameters BootArgs are passed to the OS at boot time.

BootArgsDHCP are passed to the network at boot time.

BootFiles describe OS boot location.

UnattendedInstallTemplate is an XSL file describing installation.

Pre Install Script Points to a script that runs on the Studio appliance during VM provisioning, before OS installation begins. This script turns the packages directory into a suitable repository for the OS installer.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:PreInstallScript

Post Install Script Points to a script that runs on the provisioned VM after OS installation. Its adds users, makes disks, and may install application packages.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:PreInstallScript

Post Script Repository and Package Lists

Repository list and package list for internal use.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:PostScriptRepoListvadk:PostScriptPackageList

VADK Packages URL and paths of package repository, source directory, and target directory.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:VADKPackages




134 VMware, Inc.

ISO Path URL from where the ISO is downloaded or accessed. Both file:// and http:// protocols are supported, but if the http:// protocol is used, it may take a very long time for the first build to download the ISO image. For that reason, the default build profile templates specify a file:// location on VMware Studio in which you place a predownloaded ISO image. Make sure that the ISO URL is valid and reachable.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:ISO/@vadk:path

ISO MD5 An ISO downloaded from the ISO URL should have the same MD5 checksum shown here.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:ISO/@vadk:md5sum

Distribution Vendor, release number, architecture, package format, package manager, and package repository.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:Distribution

OS Package List List of packages from the OS install media to be included in the virtual machine. No packages can be removed from the required list of packages.

//ovf:Envelope/Section[@xsi:type='vadk:JEOSSection_Type']/vadk:OSPackages

Build Settings The BuildSection controls provisioning of the VM.

VM Network Connection Network Connection allows you to specify either Bridged or Host‐only option. The network mode is always reset to bridged prior to ZIP and OVF packaging. The Network Connection can also specify the network label for VMware vSphere, VM Network for example.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningSettings/vadk:NetworkConnection

VM Network Type VMware Studio provides two options for obtaining the IP address of the transitory virtual machine that is built during provisioning: DHCP or static IP address. Specify one of the following:

DHCP

Static, which necessitates the items below.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningSettings/vadk:NetworkType

IP Address – the static IP address to be used for the virtual machine during provisioning.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningSettings/vadk:IP

Netmask – The netmask to be used for the virtual machine during provisioning. A netmask enables the recipient of IP packets to distinguish the network ID and host ID portions of the IP address. Netmasks normally are of the format 255.x.x.x.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningSettings/vadk:Netmask

Gateway – The IP Address of the designated gateway for this network.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningSettings/vadk:Gateway

Preferred DNS Server (Optional) – The primary DNS server to be used for the virtual machine during provisioning. A name server is responsible for mapping IP addresses to names.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningSettings/vadk:DNS1

Alternate DNS Server (Optional) – The alternate DNS server to be used for the virtual machine during provisioning. A name server is responsible for mapping IP addresses to names.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningSettings/vadk:DNS2

Host Name(provisioning platform)

The host name or IP address of the virtualization platform you use for provisioning.

Not all information items are required for different platforms. For example, only VMware Workstation needs the vmrun command, and the build directory path is needed only for hosted products.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:hostname

Port The port for communicating with the remote host that performs provisioning. For many virtualization platforms this is HTTPS port 443. VMware Workstation uses SSH on port 22 for remote provisioning, so it does not ask for a port number.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:port



VMware, Inc. 135


Host OS The operating system of the provisioning platform.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:hostOS

Username A user name on the remote host for authentication of virtual machine provisioning.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:login


//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:password

Build Directory Path (Workstation) The temporary path used by the provisioning platform to register and control provisioning of the virtual machine. This location is used to store the virtual machine during the provisioning phase. For example, if a Linux system is the host of VMware Workstation and /tmp is the provisioning directory, then enter /tmp in the Host Path field.

As an alternate example, if a Windows system is the host of VMware Workstation and c:\tmp is the provisioning directory, SCP uses the OpenSSH server in Cygwin, so the Host Path is c:\tmp but the File Transfer Path below should be /cygdrive/c/tmp.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:path.

Datastore Name Datastore name as shown in the VMware vSphere client Summary page. This name could be datastore1, storage1, or some other designation.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:datastore

Datacenter Name (vCenter only) Datacenter name as designated in the VMware vSphere inventory. This name appears in the left sidebar of the vSphere client when connected through vCenter Server.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:datacenter

Managed ESX Host (vCenter only) Host name or IP address of the ESX/ESXi host managed by vCenter.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:managedESX

Resource Pool (Optional) If you created a Resource Pool and you want VMware Studio to be part of it, you can specify the name of the resource pool. Optional. ESX/ESXi hosts and vCenter Server have a built‐in default resource pool, Resources. This resource pool is visible in the Managed Object Browser (MOB) interface at http://<esx‐or‐vc>/mob, but the vSphere Client, VMware Studio, and ovftool do not support it. If you want to set a resource pool, use one that was created, not Resources.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:resourcePool

File Transfer Username Username used to transfer provisioning VM files to and from the provisioning platform host.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:fileLogin

File Transfer Password Password used to authenticate the file transfers to and from the provisioning platform host.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:filePassword

File Transfer Protocol Protocol used to communicate between the provisioning platform host and the VMware Studio appliance. Ensure that communication using the specified protocol works between the VMware Studio appliance and the host where the provisioning platform runs.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:fileProto




136 VMware, Inc.

Useful Attributes Not Displayed in the VMware Studio Web Console/ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningTimeouts follow:

@vadk:boot="600" – New name for vadk:pxe. Maximum wait time (in seconds) to discover the network

address of the transient VM during provisioning.

@vadk:hang="7200" – Maximum time (in seconds) for provisioning to complete.

@vadk:remoteDeviceBootDelay="25" – Transient VM boot delay (in seconds) that allows its CDROM and

floppy devices to be connected.

@vadk:remoteDevice="15" – Maximum time (in seconds) for CDROM or floppy devices to connect.

@vadk:scpOperationTime="300" – Maximum time (in seconds) for the scp commands to complete.

@vadk:sshWaitTime="120" – Time (in seconds) for Studio’s ssh commands to complete. If you see any

failures related to ssh, increase this setting, although doing so may prolong overall build times.

@vadk:systemCmdWaitTime="30" – Maximum time (in seconds) for VMware Studioʹs ovftool and remoteDeviceConnect commands to report their initial responses.

@vadk:systemCmdMaxTime="7200" – Maximum time (in seconds) for VMware Studioʹs ovftool and remoteDeviceConnect commands to complete.

/ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:wsXDisplay=”0.0” – X11 display configuration to display the VMware Workstation

console on a Linux host. VMware Workstation provisioning fails if this attribute is not set accordingly.

File Transfer Path A path used by VMware Studio for uploading the provisioning virtual machine to the host path. The File Transfer Path and the Build Directory Path must refer to same physical directory. For example, if Linux hosts VMware Workstation and /tmp is the provisioning directory, both File Transfer Path and Build Directory Path would have /tmp as their entries. As another example, if Windows is the host of VMware Workstation and c:\tmp is the provisioning directory, Build Directory Path might be c:\tmp while File Transfer Path might be /cygdrive/c/tmp, because that is the name of the same location when OpenSSH for Windows is installed for the SSH service.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:filePath

Path to vmrun Command (Workstation only) VMware Workstation uses the vmrun command for provisioning.

On Windows this could be C:\Program Files\VMware\VMware Workstation.

On Linux this could be /usr/bin.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostLan/@vadk:vmrunPath

Virtualization Platform The VMware virtualization platform for provisioning your virtual machine. A drop‐down menu displays a choice of platforms. As you select different platforms, build environment settings change.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:ProvisioningEngine/vadk:VmhostProduct vadk:name="">

Pre Install Shell Script Shell script that you can modify, which runs on the provisioned VM before installation of application packages. It may remove unneeded OS or application packages.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:PreInstallShellScript

Post Install Shell Script Shell script that you can modify, which runs on the provisioned VM after installation of application packages. It may delete unnecessary files.

//ovf:Envelope/Section[@xsi:type='vadk:BuildSection_Type']/vadk:PostInstallShellScript

EVM Scripts For installation of an existing VM, and for preinstallation of the new VM based on it.

//ovf:Envelope/Section[@xsi:type='vadk:ExistingVMSection_Type']/vadk:EVMInstallScript//ovf:Envelope/Section[@xsi:type='vadk:ExistingVMSection_Type']/vadk:PreInstallScript



VMware, Inc. 137


Customizing the Footer in the Web ConsoleYou can customize the left‐side footer and the middle footer text for a VM Web console. To do this, edit the VM

profile and add HTML tags as in this example to the ViewCustomization XML section:

<Section xsi:type="vadk:VAMISection_Type"><vadk:ViewCustomization><vadk:FooterLeft><a href="http://www.vmware.com/"

target="_blank"><img style="padding-top: 3px;" src="service/core/vmware-footer-logo.gif" alt="VMware logo" border="0" /></a></vadk:FooterLeft>

<vadk:FooterCopyright>Copyright © 1998-2009 VMware, Inc. All rights reserved.</vadk:FooterCopyright>

<vadk:CopyrightDialog>Copyright © 1998-2011 VMware, Inc. All rights reserved.</vadk:CopyrightDialog>

</vadk:ViewCustomization></Section>

As shown in the example, the footer HTML must be XML encoded. If it contains any images, make sure that

the images are accessible to the Web console of your virtual appliance.

Creating Virtual Disks, Partitions, and Virtual DevicesThe following sections provide information about the virtual hardware that is defined in the build profile for

a virtual machine. In the VMware Studio Web console UI, this information is defined in the Hardware tab.

Controllers

An example controller specification looks like this:

/ovf:Envelope/Section[@xsi:type='ovf:VirtualHardwareSection_Type'] ...<Item>

<rasd:BusNumber>0</rasd:BusNumber><rasd:Caption>SCSI Controller 0 - LSI Logic</rasd:Caption><rasd:InstanceId>4</rasd:InstanceId><rasd:ResourceSubType>lsilogic</rasd:ResourceSubType><rasd:ResourceType>6</rasd:ResourceType>

</Item>

rasd:BusNumber – The controller number. Controller 0 on hard drive 0 is defined to be the boot device.

Four controllers are supported (0‐3).

rasd:Caption – A text description of the controller.

rasd:InstanceId – The order of this Item in the hardware section.

rasd:ResourceSubType – Supported types for SCSI controller are lsilogic and VirtualSCSI (these names are case sensitive). Controller type VirtualSCSI, also called Paravirtualized SCSI or PVSCSI, requires a VM with virtual hardware version 7 or higher. The ResourceSubType element is not present in

the Studio Web console UI, so to modify this element, you must manually edit the build profile XML file.

After the VM build, VirtualSCSI gets inserted into OVF as the specified controller type.

rasd:ResourceType – The type of controller. Resource type 6 indicates SCSI controller. See section

“Resource Allocation Setting Data” on page 140.

Hard Disk Drives

An example of a hard drive looks like this:

<Item><rasd:AddressOnParent>1</rasd:AddressOnParent><rasd:Caption>Harddisk 1</rasd:Caption><rasd:HostResource>/disk/newdisk</rasd:HostResource><rasd:InstanceId>5</rasd:InstanceId><rasd:Parent>4</rasd:Parent><rasd:ResourceType>17</rasd:ResourceType>

</Item>


138 VMware, Inc.

rasd:AddressOnParent – The hard drive address on the controller. Fifteen hard drives per controller are

supported, numbered 0‐15, with address 7 being reserved.

rasd:Caption – A text description of the hard drive.

rasd:HostResource – A string that associated this hard drive with an associated entry in the DiskSection.

This entry always begins with /disk/ followed by the ID from the entry in the DiskSection.

rasd:InstanceId – The order of this Item in the hardware section.

rasd:Parent – The controller on which the hard drive is to reside. This number is the InstanceId of the controller, not the controller number.

rasd:ResourceType – The type of hardware device. 17 is a hard drive.

Disk

This section defines the name, size, and format of the virtual hard drives that appear in the virtual machine.

The following is an example of a disk specification:

/ovf:Envelope/Section[@xsi:type='ovf:DiskSection_Type'] ...<Disk ovf:diskId="newdisk" ovf:capacity="2048"

ovf:capacityAllocationUnits="MegaBytes"ovf:format="http://www.vmware.com/specifications/vmdk.html#sparse"ovf:fileRef="newdisk.vmdk"

/>

ovf:diskId – ID of this disk. The ID matches this disk with a hard drive defined in the Hardware section.

ovf:capacity – The size of the disk, in ovf:capacityAllocationUnits.

ovf:capacityAllocationUnits – The size units. MegaBytes are the supported value.

ovf:format – The format of the vmdk file. This value should always be:

http://www.vmware.com/specifications/vmdk.html#sparse.

ovf:fileRef – The name of the generated file for this disk.

Partition

This section defines the partitions on the disks specified in the Disk section. For example:

/ovf:Envelope/Section[@xsi:type='vadk:DiskPartitionSection_Type'] ...<vadk:Partition vadk:mount="/newdisk" vadk:fs="ext3" vadk:bootable="0" vadk:diskId="newdisk"

vadk:size="grow"/>

vadk:mount – The place where the disk appears on the virtual machine’s file system. This field is ignored

for partitions marked swap.

vadk:fs – The type of partition to make. A standard file system will have the value ext3; the other valid value is swap to define a swap partition to extend the virtual memory of the virtual machine.

vadk:bootable – Whether this partition is bootable or not. This flag is set only in the root partition

(controller 0, disk 0) and only on the boot partition.

vadk:diskId – The ovf:diskId in the Disk section to which this partition refers.

vadk:size – Size of the partition. Normally, each new disk has only one partition, specifying the entire

disk. This is specified with the word grow in this attribute. Otherwise, a value may be entered here that

specifies the size of the partition in MB. A grow partition should be the last partition specified in the disk.

VMware, Inc. 139


Ethernet Adapter

An example ethernet adapter specification looks like this:

/ovf:Envelope/Section[@xsi:type='ovf:VirtualHardwareSection_Type'] ...<Item>

<rasd:AutomaticAllocation>true</rasd:AutomaticAllocation><rasd:Caption>Ethernet adapter on vmnet</rasd:Caption><rasd:Connection>Network 1</rasd:Connection><rasd:InstanceId>3</rasd:InstanceId><rasd:ResourceSubType>PCNet32</rasd:ResourceSubType><rasd:ResourceType>10</rasd:ResourceType>

</Item>

rasd:Connection ‐ Logical ethernet adapter name.

rasd:InstanceId ‐ The order of this Item in the hardware section.

rasd:ResourceSubType ‐ Supported types for network adapters are PCNet32, E1000, VmxNet, and VmxNet3 (all case sensitive). Type VmxNet3 requires a VM with virtual hardware version 7 or higher.

See KB article http://kb.vmware.com/kb/1001805 for specific requirements of each Ethernet adapter type.

The ResourceSubType element is not present in the Studio Web console UI, so to modify this element,

you must manually edit the build profile XML file. After the VM build, VmxNet3 gets inserted into OVF as the specified adapter type.

rasd:ResourceType ‐ Resource type 10 indicates network adapter. See “Resource Allocation Setting Data”

on page 140.

Virtual Sound Card

To add a virtual sound card to the virtual machine, insert the following into the build profile section,

<Section xsi:type="ovf:VirtualHardwareSection_Type">, replacing the instance number with the

next number in sequence in your hardware section.

<Item><rasd:Caption>es1371 sound controller</rasd:Caption><rasd:InstanceId>7</rasd:InstanceId><rasd:ResourceSubType>es1371</rasd:ResourceSubType><rasd:ResourceType>35</rasd:ResourceType>

</Item>

Virtual USB Controller

To add a virtual USB controller to the virtual machine, insert the following into the build profile section,

<Section xsi:type="ovf:VirtualHardwareSection_Type">, replacing the instance number with the

next number in sequence in your hardware section.

<Item><rasd:Caption>USB controller</rasd:Caption><rasd:InstanceId>8</rasd:InstanceId><rasd:ResourceType>23</rasd:ResourceType>

</Item>

Logical Volume Management in Build ProfileThe Logical Volume Management feature of Studio helps the user to build VMs with additional application

disks whose disk size can be increased. The user allocates a new disk and attaches it to the LVM; the size of

this disk is modified using command line utilities or user interface options provided by the ISVs. The user can

now set the LVM flag in the UI, while creating the build profile.

Signing OVF FilesBuild profiles from VMware Studio 2.1 and later contain a new “post‐output creation script” mechanism. The

DistributionFormat element allows user‐supplied scripts to run after generation of the build output file

(OVF, OVA, or ZIP). Scripts allow unattended manipulation of build results. You can sign the OVF using this

mechanism. A sample script that calls the signovf command is included in newly generated Studio profiles.


140 VMware, Inc.

The effect of signing an OVF can be seen only when deploying to ESX/ESXi 4.1 or through vCenter Server 4.1.

The OVF‐based certificate is ignored in earlier versions of VMware vSphere.

The XML profiles contain a sample signing program that accepts an OVF‐style privacy enhanced mail (PEM)

file, or in the absence of a PEM file, generates a self‐signed key, with which to sign the OVF.

signovf -p <PEM_file> [-s subject] <OVF_file>

You can specify the -s option with an X500‐like parameter for signing, so openssl does not have to ask for that information interactively. For example:

signovf -p mail.pem -s '/C=US/ST=Some-State/O=AnyCompany/CN=Self-Signed' appliance.ovf

Unmounting CDROM or ISO After a BuildIn Studio 2.1 and later you can change the ISO element vadk:unmountAfterUse in the build profile. The default is false. When set to true, the ISO is unmounted after a build. This is useful for unmounting the

CDROM post‐build. It is also useful when you want to mount a different ISO for the next build.

Resource Allocation Setting DataTable D‐2 shows <Item> elements in the DMTF standard. Table D‐3 shows instance IDs for various hardware.

Table D-2. DMTF RASD Standard

ElementName Required field that contains a display‐friendly message about the content of the RASD

Description Human‐readable description

InstanceID Required field that contains unique ID within this <VirtualHardwareSection>

ResourceType Required field that indicates the kind of resource

ResourceSubType A vendor‐specific identifier for specific devices

VirtualQuantity Specifies the amount (used for memory and CPU)

AllocationUnits Specifies the unit of resource (used for memory and CPU)

Reservation Specifies resource allocation policy (CPU and memory)

Limit Specifies resource allocation policy (CPU and memory)

Weight Specifies resource allocation policy (CPU and memory)

Address Typically used as the unit number of a controller

Parent Instance ID of parent controller (for devices on a controller)

AddressOnParent Used to specify the order for devices on a controller

AutomaticAllocation Used to specify whether a device should be connected on power‐on (e.g., for a CDROM)

Connection Reference to a network for an ethernet adaptor

HostResource Reference to a virtual disk for a disk drive

Table D-3. Resource Type Numbering

Processor 3

Memory 4

IDE Controller 5

SCSI Controller 6

Ethernet Adapter 10

Floppy Drive 14

CD/DVD Drive 15/16

Disk Drive 17

USB Controller 23

VMware, Inc. 141


Structure of vApp XML Build ProfilesAfter you build a vApp, you can find its XML profile in this location on the VMware Studio appliance:

/opt/vmware/var/lib/build/vapp_profiles/<vAppProfileName>.xml

Table D‐4 describes the configuration properties in the vApp build profile XML file.

Table D-4. vApp Build XML Configuration Properties


vApp Information Items in the ProductSection for the ISV.

vApp Name Name of the vApp. This name is displayed as vApp in vSphere. //vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Product

Version Version of the vApp. This version is displayed in the Summary tab in vSphere client.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Version

Full Version Free text used to display the full version of the vApp.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:FullVersion

Product URL Product URL to the company’s Web site which provides information about this vApp.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:ProductUrl

Vendor Name of the vApp vendor.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Vendor

Description Description of the functionality this vApp provides. It is displayed in the summary tab in vSphere client.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:AnnotationSection/ovf:Annotation

Vendor URL Vendor URL to the company’s Web site.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:VendorUrl

Application URL URL to the main application Web page. The {$app.ip} keyword in the URL is resolved to the IP address of the VM.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:AppUrl

EULA Text end‐user licensing agreement for the vApp. The user must accept this agreement before using the vApp. You can add more than one EULA in the build profile by copying the <EulaSection>.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:EulaSection/ovf:License

VM Information You can specify more than one virtual machine in VMCollection.

Profile Name Specifies the profile name of the VM.

//vadk:MultiVM/vadk:VMCollection/vadk:VM/@vadk:profile

Location If specified, it is used to select an existing build of a VM. If vadk:location is specified, then the VM at that location is used. Otherwise, the VM is built from the profile specified in the vadk:profile.

//vadk:MultiVM/vadk:VMCollection/vadk:VM/@vadk:location

Id This is the identification of the VM, used in the Startup Section. This id is auto‐generated by the UI.

//vadk:MultiVM/vadk:VMCollection/vadk:VM/@vadk:ovfid

Start Order The StartupSection describes power‐on order for the vApp.

Id Specify the id of the VM. This matches the vadk:ovfid in the VMCollection Section.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:StartupSection/ovf:Item/@ovf:id

Boot Group Specify the boot group to order the startup and shutdown of the VMs.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:StartupSection/ovf:Item/@ovf:order

Start Action Action to perform on the VM while starting the vApp. It can either be specified as powerOn or ignored.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:StartupSection/ovf:Item/@ovf:startAction

Stop Action Action to be performed on the VM while shutting down the vApp.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:StartupSection/ovf:Item/@ovf:stopAction


142 VMware, Inc.

Start Delay Number of seconds to wait for the VM to power on before continuing with the start sequence.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:StartupSection/ovf:Item/@ovf:startDelay

Stop Delay Number of seconds to wait for the VM to power off before continuing with the stop sequence.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:StartupSection/ovf:Item/@ovf:stopDelay

Tools If selected in the UI (set to “true” in the profile), wait until VMware Tools is running before continuing with the start sequence.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:StartupSection/ovf:Item/@ovf:waitingForGuest

Resources Specifies vSphere Resources allocated for the vApp.

OVF ID Specify the ID of the VM. This matches the vadk:ovfid in the VMCollection Section.

//vadk:MultiVM/vadk:Resources/vadk:Resource/@vadk:ovfid

CPU Shares The priority of this VM relative to others when non‐reserved CPU is available.

//vadk:MultiVM/vadk:Resources/vadk:Resource/vadk:cpu/@vadk:weight

CPU Reservation (Mhz)

Guaranteed lower bound on the amount of CPU that the host reserves for this VM.

//vadk:MultiVM/vadk:Resources/vadk:Resource/vadk:cpu/@vadk:reservation

Memory Shares The priority of this VM relative to others when non‐reserved memory is available.

//vadk:MultiVM/vadk:Resources/vadk:Resource/vadk:memory/@vadk:weight

Memory Reservation(MB)

Guaranteed lower bound on the amount of CPU that the host reserves for this VM.

//vadk:MultiVM/vadk:Resources/vadk:Resource/vadk:memory/@vadk:reservation

Output Specifies the DistributionFormat for output.

File Name Name of the vApp OVF and OVA output files.

//vadk:MultiVM/vadk:DistributionFormat/@vadk:filename

Output Format OVF or an OVA format can be used to deploy the vApp into vCenter Server using vSphere Client.

//vadk:MultiVM/vadk:DistributionFormat/@vadk:format

Application URL VM Selects the VM to which the application URL should point. It is used in configuring the Application URL specified in the Description tab. vadk:appurl is set to the word “true” if this VM is to be selected.

//vadk:MultiVM/vadk:VMCollection/vadk:VM/@vadk:appurl

OVF IP Assignment The IpAssignmentSection specifies how to handle OVF network specifications.

DHCP Enable the option of using the DHCP server for configuring networking of the VM.

//vadk:MultiVM/vmw:IpAssignmentSection[@vmw:schemes=”dhcp”]

OVF Environment Enable the option of using a fixed or a transient IP address for the VM.

//vadk:MultiVM/vmw:IpAssignmentSection[@vmw:schemes=”ovfenv”]

OVF Property The Property section sets OVF properties for the vApp.

Key Key to the OVF Property.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Property/@ovf:key

Label Label for the OVF property.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Property/@ovf:Label

Description Description for the OVF property.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Property/@ovf:Description

Type Type of the OVF property

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Property/@ovf:type

Table D-4. vApp Build XML Configuration Properties (Continued)


VMware, Inc. 143


Default Value Value of the OVF property according to the type.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Property/@ovf:value

User Configurable Whether to prompt user to allow changing property.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Property/@ovf:userConfigurable

OVF Qualifiers OVF‐standard type qualifiers.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Property/@ovf:qualifiers

VMW Qualifiers VMware‐specific type qualifiers.

//vadk:MultiVM/ovf:VirtualSystemCollection/ovf:ProductSection/ovf:Property/@vmw:qualifiers

Table D-4. vApp Build XML Configuration Properties (Continued)



144 VMware, Inc.

VMware, Inc. 145

E

This appendix contains two sections:

“Resolving VMware Studio Issues” on page 145

“Resolving Eclipse Plugin Issues” on page 149

Resolving VMware Studio IssuesTable E‐1 lists problems that you might encounter when using VMware Studio, and provides possible

resolutions for these problems.

O

Troubleshooting E

Table E-1. Troubleshooting Information for VMware Studio

Problem Resolution

Troubleshooting VM Builds

Windows build fails with an “account already exists” error.

Windows Server already has a guest user account. If you try to create one, it causes builds to fail.

The build of a VM or vApp hangs or times out without any specific error.

Check the provisioning engine console to see if user input is needed or if there is a specific failure. This can happen because you specified an OS package in the build profile that does not exist as part of the ISO; in that case, remove the OS package.

VMware Studio times out waiting for IP information from the provisioning VM during build.

This problem has several possible causes:

1 Your DHCP server might be having trouble issuing an IP address. The alternative is to use a static IP address during provisioning. Obtain an IP address in your network, and update the virtual machine Network Type.

2 If you try to provision a 64‐bit OS on a 32 bit ESXi host, VMware Studio times out waiting for IP information from the VM, which cannot power on. The message on the console of the provisioning machine would be “Your CPU does not support long mode. Use a 32‐bit distribution.”

3 When an ESX/ESXi host is managed by vCenter Server, and you provision directly on the ESX/ESXi host, not through vCenter Server, the provisioning might fail. This is not a supported configuration: next time provision through vCenter Server.

A build fails and prints many messages including:

Error: unable to open NFC target disk.

This could be a permissions problem. When network shares serve files and directories owned by different users, remote build transfer can fail. Try building to local disk instead of building to a network. share.

Provisioning a 64‐bit OS fails when using 32‐bit hardware to run a virtualization product platform. The verbose log contains this error message: “THE CHOSEN PROVISIONING ENGINE DOES NOT APPEAR TO BE CAPABLE OF RUNNING 64‐BIT GUESTS; THE BUILD MAY NOT BE SUCCESSFUL.”

You must use 64‐bit hardware to provision a virtual machine with 64‐bit guest operating system. If the CPU is an Intel or AMD processor, it must be capable of executing 64‐bit instructions. Intel processors must have VT (virtualization technology, which Intel cpuid documentation also calls the VMX bit) enabled. Sometimes this setting is in the BIOS.


146 VMware, Inc.

During operating system installation in a VM build, the /boot partition size causes the build to fail.

Check the /var/log/syslog and see if there are disk full errors. If so, you can increase the size of your /boot partition in the Hardware tab of the build profile.

Instance names which begins with period (.) or hyphen (‐) result in UI unresponsiveness.

This can happen if the profile name starts with a period or hyphen, or if you enter an instance name with the createbuild command. The solution is to delete all instances that start with a period or hyphen using the studiocli command.

A Studio build fails with this message:

Provisioning Agent: failed to run script “.post.sh”

The cause could be that rpmbuild searched for dependencies and found some files missing, even though they are not really required. The workaround is to create a package instead of using the post‐install script to copy the files involved.

While building an Ubuntu VM you may see one of these two postinstall.log error messages:

W: Conflicting distribution: http://10.20.30.123 stable Release.WARNING: The following packages cannot be authenticated!

You can ignore these warning messages.

You do not need to run apt-get update to correct this problem.

Unable to build Ubuntu virtual machines that contain more than 15 virtual disks.

The Ubuntu installer limits you to creating no more than 15 disks during OS installation process, and VMware Studio follows this restriction. To add more than 15 disks, add them after the VM is built by VMware Studio.

The Studio Web console does not accept host names, for example host names containing underscore (_).

Use the numeric IP address to connect to the provisioning engine or update repository server.

Disk partitioning for your virtual machine has partitions assigned to the wrong mounts.

Ensure that if you assign a partition with size=grow’ that it is the last partition on the disk.

Update package build fails, but a ZIP or OVF file is created.

This problem can be caused by not changing the version number for the update package. The package has new content, but the version number is the same as a previous package. When you create an update package, change the version number.

The problem can also occur if the application packages are of the same version, but different checksum

When building RHEL, CentOS, or SLES, the message “Error: RPM failed: ... vmware.drv.so ... conflict” appears while installing VMware Tools.

You can ignore this error message. VMware Studio overwrites the OS package vmware.drv.so with a valid vmware.drv.so during the build process.

When provisioning a virtual machine on an ESX/ESXi host that is managed by vCenter Server, the build is successful, but an orphaned instance of the machine remains in the inventory afterwards.

The workaround is to delete the orphaned virtual machine from the inventory using the vSphere Client connected to vCenter.

Next time, provision through the ESX/ESXi host’s managing vCenter Server to avoid this problem.

The build fails with the following fault string:

fault.RestrictedVersion.summary

Provisioning through ESXi with the free ESXi license produces this error because the required ESXi capabilities for provisioning are not available. The ESXi evaluation license (which expires in a given period) or a paid license will solve this issue.

Workstation fails to build a VM with the warning:

Failed to detect a powered-up transient VM.

Check that there are no networking related problem by running ssh from the Studio appliance to the Workstation host.

Make sure you entered a valid Path to vmrun command. For instance, enter /usr/bin not /usr/bin/vmrun for Linux, or enter C:\Program Files\VMware\VMware Workstation not C:\Program Files\VMware\VMware Workstation\vmrun.exe for Windows.

If the symptom was that the transient VM could not be powered on, or that the VM was not seen on the Workstation console, verify that the user entered in the Build Settings (for Workstation provisioning) matches the user who is currently running the Workstation console on its host. If the host is running a Linux OS, also verify that the vadk:wsXDisplay in the build profile (default ":0.0") matches the correct X windows DISPLAY environment variable.

Table E-1. Troubleshooting Information for VMware Studio (Continued)

Problem Resolution

VMware, Inc. 147

Appendix E Troubleshooting

When validating file transfer to Workstation, this error appears in the log file:

<build/update host> could not be reached!

This could be due to port 7 or port 22 being closed. See the prerequisites section for “Prerequisites” on page 21.

Port 7 but also be open on the host of the Update Repository.

VMware Workstation gives this error during a build:

Login error: Insufficient permissions in host operating system

Ensure that you have the correct credentials for Workstation in the Build Settings.

After existing VM discovery and import, the VM built from it cannot deploy, returning an “I/O error” or “Error 500” code. In vCenter Server and ESX/ESXi 4.1, the error is properly reported as “capacity of disk is larger than requested.”

One cause is that during discovery, disk sizes were calculated too small. Because of rounding errors when converting from disk cylinders to MB, virtual disk size is sometimes calculated one or two MB smaller than needed. The solution is to increase the size of the disks in the generated build profile to be match what is required. The size is represented in MB in the ovf:capacity attribute of Disk elements in the DiskSection_Type section.

//ovf:Envelope/Section[@xsi:type="ovf:DiskSection_Type"]/Disk/@ovf:capacity

The build fails with a message like this:

STUDIO ABORT: Error: Unable to install package “pkg-name”

This might happen when the configuration files in a previous build get out of sync with those in an updated package.

The solution is to modify the pre‐install script to remove and purge the old package.

Troubleshooting VM Power-On

VMware Studio appliance does not get an IP Address assigned.

Go to VMware Studio console, and use the “Configure Network” option on VMware Studio welcome screen.

During the first boot of a virtual machine, the virtual machine stops running before reaching the login prompt. Restarting the virtual machine results in the First Boot Script being skipped.

Discard the virtual machine and start over with the virtual machine OVF or ZIP file.

A Linux VM created by VMware Studio in OVF format, when imported into VMware Workstation with the Workstation Conversion Wizard, fails to boot with a kernel panic error. A log file might say that the Buslogic SCSI adapter is not supported.

To work‐around this known issue in the VMware Converter version that supports the Workstation Conversion Wizard, edit the .vmx file of the VM that the Conversion Wizard created. Replace “buslogic” with “lsilogic” on the scsi0.virtualDev line, and power on the VM.

When you provision on Workstation and check the Retain Transient VM option, which calls the –debug CLI flag, the transient VM left after the build does not boot up manually. The VM starts, and the provisioning agent shows signs of executing, but the VM soon powers down so you effectively cannot do anything with it.

The cause is that the provstart.iso image is requested but not available to the transient VM, so the provisioning agent cannot execute scripts in the provstart.iso image at boot time. A workaround is to reconfigure the VM so its CDROM connects to the physical drive instead of provstart.iso, rebuild and reboot the VM. If the provisioning agent does not see provstart.iso, the VM will boot and function as you expect.

After provisioning the transient VM goes offline, looks for the post‐OS installation log file, but does not find it, so the build fails.

The cause could be a temporary loss of network connectivity, or slow server response. Run the build again.

After you set an appliance to use a static IP address, its IP address might revert to the DHCP setting that it used previously.

One cause is persistence of the dhclient process, which could change the network settings when its DHCP lease expires.

The solution is to log into the appliance as root, kill the dhclient process, and run the /etc/rc.d/network restart command to reset networking.


Problem Resolution


148 VMware, Inc.

VMware Studio 2.1 and later provide the vamisupport script, which bundles up log files into a tar file (tarball) for troubleshooting. This script is at /opt/vmware/bin/vamisupport on VMware Studio generated

appliances. When reporting a problem, the customer can run the vamisupport script, and note where the

script writes its output. The customer can scp the resulting tarball to a computer with email service, then send

it with their report.

Troubleshooting After Deployment

Networking parameters could revert to their deploy‐time settings after a reboot. This occurs with VMs deployed under vCenter Server, when you change network settings with the blue screen login instead of with the Web console UI.

When you deploy a VM under vCenter Server, you are given a choice of networking configuration (DHCP, Fixed, or Transient) and you may assign an IP address to the VM. Once the VM is running, VAMI allows the UI to do network reconfiguration of the VM. However vCenter Server does not know if the network was reconfigured. There is a flag in the VM that tells the VAMI code run at boot time that networking was reconfigured in the VM, so ignore the network parameters from vCenter Server.

This works fine if you use the Web console UI to reconfigure the network. However, the blue screen network configuration does not set this flag, so the next time the VM is booted, networking parameters are set to their state when the VM was first deployed.

The workaround is to edit the network flag manually. To do this, change the value of the ovf attribute in the network element of /opt/vmware/etc/vami/vami_ovf_info.xml from true to false. In other words, find this section:

<?xml version="1.0"?><ovf-info>

<eula ovf="true"/><network ovf="true"/>

</ovf-info>

Change it to this:

<?xml version="1.0"?><ovf-info>

<eula ovf="true"/><network ovf="false"/>

</ovf-info>

RHEL 6.0 OS installation freezes with popup dialog indicating that a legitimate RPM cannot be opened on the VM console. TTYs other than TTY1 (usually Alt‐F4) reveals the expiration of the initial DHCP address.

In the popup dialog you may select to Retry and the OS installation should be able to proceed, if it succeeded in retrieving a new DHCP address. Alternatively, use a static IP address for provisioning (while building the VM) to bypass the DHCP dependency.


Problem Resolution

VMware, Inc. 149

Appendix E Troubleshooting

Resolving Eclipse Plugin IssuesTable E‐2 lists problems that you might encounter when using the VMware Studio Plugin for Eclipse.

Table E-2. Troubleshooting Information for the Eclipse Plugin

Problem Resolution

Troubleshooting the Studio Plugin for Eclipse

Why is it taking so long to install the VMware Studio Plugin for Eclipse?

The Eclipse installer is probably searching the external Web for dependencies. Set the HTTP proxy in Eclipse as in “Getting Started with VMware Studio Plugin for Eclipse” on page 75.

Why does Eclipse hang at start‐up time? It is possible that Eclipse is trying to update or install plugins from an obsolete or nonexistent software site. You can remove old locations from the list of available software sites as follows.

In Eclipse 3.4: Help > Software Updates > Manage Sites > [click box to dim] > Remove.

In Eclipse 3.5: Window > Preferences > Install/Update > Available Software Sites > [click site] > Remove

What can I do about an invalid security certificate, with error code sec_error_ca_cert_invalid saying the certificate is not trusted because it is self‐signed?

The VMware Studio Plugin for Eclipse uses the default Web browser that is configured in Eclipse. You should set this configuration to use a supported browser.

If the configuration is set to an embedded Mozilla, such as Firefox on Linux, and is using xulrunner >=1.9 (Gecko layout), certificate validation might fail without an easy way to bypass it. Typically you see a message such as the following in a pop‐up:

x.x.x.x:5480 uses an invalid security certificate.The certificate is not trusted because it is self signed.The certificate is only valid for <a id="cert_domain_link"

title="Self-Signed by VMware, Inc."> Self-Signed by VMware, Inc.</a>

You have a choice of two workarounds:

Configure Eclipse to open an external browser. To do this, click Window > Preferences > General > Web Browser > Use External Web Browser.

Open the VMware Studio Web console in a regular browser window and separately establish the certificate override:

In Firefox 3 for example, click Or you can add an exception > Add Exception > Get Certificate > Confirm Security Exception.

Copy the certificate override file from your Web browser profile to the Eclipse profile:cd $HOME/.mozillacp firefox/*default/cert_override.txt eclipse/

Restart Eclipse.


150 VMware, Inc.

VMware, Inc. 151

A appliance

Used to designate purpose‐built hardware, but now designates virtual machines with a specific function.

B build profile

For VMware Studio, a set of XML files that govern how a virtual appliance gets assembled and built.

C CIM

Common Information Model, a DMTF standard used primarily for health monitoring in datacenters.

CIMOM

CIMOM is the CIM object manager, or broker (SFCB is the small footprint CIM broker) acting as the

management agent for VAMI.

CLI

Command line interface. VMware Studio has many: studiocli, mkpkg, vamimanager, and signovf.

D DEB

Software package format used for the Debian project and Ubuntu Linux.

DHCP

Dynamic host configuration protocol, where servers provide host names, IP addresses, and DNS servers.

DNS

Domain name system, a system that translates host names into IP addresses on the Internet.

E ESXi

Elastic Sky X (ESX) pared down to a bare‐metal server to run virtual machines in a datacenter.

EULA

End user license agreement.

G Gateway

In an IPv4 network, controls the gating of subnets to each other. Also called router. The netmask informs

the gateway how many bits in an IP address to disregard when routing.

I IDE

Integrated development environment, for example Eclipse.

IPv6

Internet Protocol version 6, with larger IP addresses for more expansion capability.

Glossary


152 VMware, Inc.

ISO image

Short form of ISO 9660, the international standard for writing a file system image on CD or DVD.

O OSP

Should be OSSP for operating system specific package, a precompiled form of VMware Tools.

OVF

Open virtualization format, a DMTF standard for packaging virtual machines. OVA is an OVF archive.

P proxy

In this context, a security server that transmits HTTP(S) requests and responses through a firewall.

R RHEL

Red Hat Enterprise Linux.

RPM

Red Hat package manager, a software package format used by Red Hat, CentOS, and SUSE.

S SSL

Secure sockets layer, a cryptographic protocol to provide communications security over the network. TLS

is the successor currently in use. SSH is a secure shell to run remote commands though SSL protocol.

SLAAC

Stateless address auto configuration, which provides automatic IP addresses in IPv6 networks.

SLES

SUSE Linux Enterprise Server. SUSE is a German acronym, Software und System‐Entwicklung.

U UTC

Universal time, coordinated. Similar to GMT (Greenwich mean time) without daylight savings.

V vApp

An object grouping of multiple virtual machines, working together.

vCenter Server (VC)

The central management application that controls virtual machines in vSphere. Formerly VirtualCenter.

VAMI (virtual appliance management infrastructure)

VMware Studio installs this runtime framework to help manage Linux appliances.

virtual appliance

A virtual machine with application software installed for dedicated use or a specific purpose.

virtual machine (VM)

A software emulation of a physical computing environment. VMware starts them from a VMX file.

VMDK

Virtual machine disk format, a file layout for VMware virtual disk. Substitutes for physical hard disk.

VSP

VMware Studio package, a file format for software package installation, independent of DEB or RPM. The

ISV user has to first create these packages, to add the applications packaged in Windows.

VUM (vCenter update manager)

A vCenter Server module that manages software updates to vSphere components.

VMware, Inc. 153

Glossary

X XML

Extensible markup language, a SGML derived way to encode documents in machine‐readable form.

Z ZIP

A compressed file archiving format, designed in 1989 and supported by Windows since 1998.


154 VMware, Inc.

VMware, Inc. 155

Index

Symbols/iso directory in datastore 88

Numerics32-bit operating systems 36

64-bit requirements 22, 30, 145

AApplication Director 15, 37

application install on Windows 83, 90

application package repositories 55

DEB or RPM format 55

location of appliancePackages 39

mkpkg command 55, 59

specification order 39

winrepo package depot for Windows 90

audience 9, 18

developers building vApps 19, 95

ISVs shipping virtual appliances 19, 101

Linux and Eclipse developers 18, 35, 75

release build automation 19, 103

Windows developers 19, 81

Bbuild profile

building a Linux VM 40, 52

building a Windows VM 83, 87

debugging build summary and logs 52, 87

migrating from earlier versions 53

procedure to build a vApp 29, 95, 99

XML structure and syntax 127

build system in VMware Studio 17

CCIMOM (CIM object manager) 46, 61

command-line options reference 103

Common Information Model (CIM) 17, 61, 109

CPU and memory, virtual 43

creating DEB or RPM packages 56

Ddatastore /iso directory needed 88

DEB package creation 56, 58

debugging

by watching build provisioning 52, 87

with build summary and logs 52, 87, 117

with vamisupport script 73, 148

deploying VMware Studio

from OVF or OVA 23

from ZIP 24

multiple hosts and single host 22

digital signatures for updates 70

digital signing of OVF files 139

discovering and importing a VM 108

discovery reports for a VM 117

disk partitioning for system and user 102

disk size and partitioning, virtual 44

EEclipse plugin 18, 75

download and install 75

management services 77

packaging applications 76

proxy for network access 75

requirements for 75

troubleshooting 149

uninstalling 78

ESX/ESXi platform support 21, 30

EULA localization and customization 43, 70, 128

existing VM as input 107

Ffield updates, See updates to virtual appliances

footprint reduction, packages and files 60

Gguest operating system support 36, 82

IISO image of operating system 30

for Linux 36

for Windows 82

network access with NFS 30

JJEOS, just enough operating system 37, 60

LLinux kernel extensions, adding 102

Mmanagement service, creating and importing 63

migrating build profiles from earlier versions 53

mkpkg command options 56


156 VMware, Inc.

Nnetwork settings

DHCP lease expiration 147

IP Pool based parameters 49, 99

prompt vSphere administrator 49, 99

proxy through firewall 26

static IP or DHCP 24, 26

NFS mount on VMware Studio appliance 30

Oold builds, removing 117

open-source VMware Tools 53

operating system image, See ISO image of OS

OSP file format for VMware Tools 53

OVF and OVA distribution formats 23, 30, 101

OVF standard (DMTF DSP0243) 13

ovfenv to retrieve OVF properties 105

Pports to open for VMware Studio 22

prerequisites for running VMware Studio 21

privileges for provisioning

on vCenter Server and ESX/ESXi 31

on VirtualCenter and ESX/ESXi 32

product key for Microsoft Windows 85

ProductRID 48, 69, 74

provisioning agent for existing VM 109

PVSCSI (VirtualSCSI) network adapter 137

Qqualifying Linux distributions 37

Rreboot the VMware Studio appliance 25

removing old builds 117

requirements for running VMware Studio 21

roadmap for reading this manual 18

RPM package creation 57, 58

Ssecurity of root account on Linux 102

security of self-signed SSL certificate 24, 124

shut down the VMware Studio appliance 25

signovf for digital signature of OVF 139

size (footprint) reduction scripts 37

SSH, installing on Windows hosts 123

storage needed for VMware Studio 21

studiocli command options 103

Ttechnical support resources 10

testing a generated appliance 52, 87

thin provisioning 23

thumbnail image of VM build 52

time zone 24

changing to local 25

for a generated Windows VM 85

troubleshooting the Eclipse plugin 149

troubleshooting VMware Studio 145

Uunmounting CDROM after a build 140

Update Manager, VMware vCenter 18, 74

Update tab

Settings > Automatic check and install updates 27

Settings > Automatic check for updates 26

Settings > No automatic updates 26

updates from local repository URL 27

updates from mounted CDROM 27

updates to virtual appliances 67

CDROM delivery of updates 69

creating updates 67

generating (building) an update 68

publishing updates 71

reboot requirement 70

retrieving an update 68

staging server and production server 68

testing your updates 72

VMware vCenter Update Manager 74

web delivery of updates 69

XML description of repository 73

ZIP archive for updates 71

Use Default Repository update default 27

user privileges, See privileges for provisioning

Vvamisupport script 73, 148

vanilla (VAMI reduced) VM 64

vaos_init.sh initialization script 64

vApp

build and deliver workflow 14

definition 13

requirements and components 95

VendorUUID 48, 69, 74

virtual appliance

best practices for development 101

definition 14

updates from update repository 67

Virtual Appliance Management Infrastructure (VAMI) 17, 61

APIs for container, I/O, and log 113

components including CIM 62

creating a management service 63

importing a management service 64

service.xml description 63

VMware, Inc. 157

Index

services for system, network, update 62

view.xml description 64

virtual hardware version, choosing 102

VirtualApp, vApp managed object 13

VirtualSCSI (PVSCSI) network adapter 137

VMware Ready program 42, 102

VMware Studio

features and architecture 15

ports to open 22

requirements to run 21

storage needed 21

troubleshooting 145

VMware Tools in generated appliances 53

VMware Tools installation 53

VMware vCenter Update Manager 18, 74

VMware virtualization platforms 23

ESX/ESXi 30

Player 30

VMware Infrastructure 3 23, 30

VMware vSphere 4 23, 30

Workstation 23, 30

VmxNet3 network controller 139

WWeb API for management services, VAMI 113

Web console for VMware Studio 16, 25, 35, 81

Application tab 46, 86

Build Settings tab 50

Description tab 42

Hardware tab 43

Management tab 46

OS tab 44, 84

Output tab 48

Windows application packaging 83

error and exit codes 90, 91

InstallShield 89

JScript support 90

library create package 90

LOGDIR environment variable 91

Microsoft installer (MSI) 89, 90

PACKAGEDIR environment variable 91

REPOSITORY environment variable 91

VMware Studio package (VSP) 89

winrepo package depot 90

workflow to build and deliver vApps 14

XXML build profile, structure and syntax 127

XML format for update repository 73

ZZIP distribution format 23, 30, 48, 71


158 VMware, Inc.