github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/builders/vmware-iso.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "VMware Builder from ISO" 4 description: |- 5 This VMware Packer builder is able to create VMware virtual machines from an ISO file as a source. It currently supports building virtual machines on hosts running VMware Fusion for OS X, VMware Workstation for Linux and Windows, and VMware Player on Linux. It can also build machines directly on VMware vSphere Hypervisor using SSH as opposed to the vSphere API. 6 --- 7 8 # VMware Builder (from ISO) 9 10 Type: `vmware-iso` 11 12 This VMware Packer builder is able to create VMware virtual machines from an 13 ISO file as a source. It currently 14 supports building virtual machines on hosts running 15 [VMware Fusion](http://www.vmware.com/products/fusion/overview.html) for OS X, 16 [VMware Workstation](http://www.vmware.com/products/workstation/overview.html) 17 for Linux and Windows, and 18 [VMware Player](http://www.vmware.com/products/player/) on Linux. It can 19 also build machines directly on 20 [VMware vSphere Hypervisor](http://www.vmware.com/products/vsphere-hypervisor/) 21 using SSH as opposed to the vSphere API. 22 23 The builder builds a virtual machine by creating a new virtual machine 24 from scratch, booting it, installing an OS, provisioning software within 25 the OS, then shutting it down. The result of the VMware builder is a directory 26 containing all the files necessary to run the virtual machine. 27 28 ## Basic Example 29 30 Here is a basic example. This example is not functional. It will start the 31 OS installer but then fail because we don't provide the preseed file for 32 Ubuntu to self-install. Still, the example serves to show the basic configuration: 33 34 ```javascript 35 { 36 "type": "vmware-iso", 37 "iso_url": "http://old-releases.ubuntu.com/releases/precise/ubuntu-12.04.2-server-amd64.iso", 38 "iso_checksum": "af5f788aee1b32c4b2634734309cc9e9", 39 "iso_checksum_type": "md5", 40 "ssh_username": "packer", 41 "ssh_wait_timeout": "30s", 42 "shutdown_command": "shutdown -P now" 43 } 44 ``` 45 46 ## Configuration Reference 47 48 There are many configuration options available for the VMware builder. 49 They are organized below into two categories: required and optional. Within 50 each category, the available options are alphabetized and described. 51 52 In addition to the options listed here, a 53 [communicator](/docs/templates/communicator.html) 54 can be configured for this builder. 55 56 ### Required: 57 58 * `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO 59 files are so large, this is required and Packer will verify it prior 60 to booting a virtual machine with the ISO attached. The type of the 61 checksum is specified with `iso_checksum_type`, documented below. 62 63 * `iso_checksum_type` (string) - The type of the checksum specified in 64 `iso_checksum`. Valid values are "none", "md5", "sha1", "sha256", or 65 "sha512" currently. While "none" will skip checksumming, this is not 66 recommended since ISO files are generally large and corruption does happen 67 from time to time. 68 69 * `iso_url` (string) - A URL to the ISO containing the installation image. 70 This URL can be either an HTTP URL or a file URL (or path to a file). 71 If this is an HTTP URL, Packer will download it and cache it between 72 runs. 73 74 * `ssh_username` (string) - The username to use to SSH into the machine 75 once the OS is installed. 76 77 ### Optional: 78 79 * `disk_additional_size` (array of integers) - The size(s) of any additional 80 hard disks for the VM in megabytes. If this is not specified then the VM will 81 only contain a primary hard disk. The builder uses expandable, not fixed-size 82 virtual hard disks, so the actual file representing the disk will not use the 83 full size unless it is full. 84 85 * `boot_command` (array of strings) - This is an array of commands to type 86 when the virtual machine is first booted. The goal of these commands should 87 be to type just enough to initialize the operating system installer. Special 88 keys can be typed as well, and are covered in the section below on the boot 89 command. If this is not specified, it is assumed the installer will start 90 itself. 91 92 * `boot_wait` (string) - The time to wait after booting the initial virtual 93 machine before typing the `boot_command`. The value of this should be 94 a duration. Examples are "5s" and "1m30s" which will cause Packer to wait 95 five seconds and one minute 30 seconds, respectively. If this isn't specified, 96 the default is 10 seconds. 97 98 * `disk_size` (integer) - The size of the hard disk for the VM in megabytes. 99 The builder uses expandable, not fixed-size virtual hard disks, so the 100 actual file representing the disk will not use the full size unless it is full. 101 By default this is set to 40,000 (about 40 GB). 102 103 * `disk_type_id` (string) - The type of VMware virtual disk to create. 104 The default is "1", which corresponds to a growable virtual disk split in 105 2GB files. This option is for advanced usage, modify only if you 106 know what you're doing. For more information, please consult the 107 [Virtual Disk Manager User's Guide](http://www.vmware.com/pdf/VirtualDiskManager.pdf) 108 for desktop VMware clients. For ESXi, refer to the proper ESXi documentation. 109 110 * `floppy_files` (array of strings) - A list of files to place onto a floppy 111 disk that is attached when the VM is booted. This is most useful 112 for unattended Windows installs, which look for an `Autounattend.xml` file 113 on removable media. By default, no floppy will be attached. All files 114 listed in this setting get placed into the root directory of the floppy 115 and the floppy is attached as the first floppy device. Currently, no 116 support exists for creating sub-directories on the floppy. Wildcard 117 characters (*, ?, and []) are allowed. Directory names are also allowed, 118 which will add all the files found in the directory to the floppy. 119 120 * `fusion_app_path` (string) - Path to "VMware Fusion.app". By default this 121 is "/Applications/VMware Fusion.app" but this setting allows you to 122 customize this. 123 124 * `guest_os_type` (string) - The guest OS type being installed. This will be 125 set in the VMware VMX. By default this is "other". By specifying a more specific 126 OS type, VMware may perform some optimizations or virtual hardware changes 127 to better support the operating system running in the virtual machine. 128 129 * `headless` (boolean) - Packer defaults to building VMware 130 virtual machines by launching a GUI that shows the console of the 131 machine being built. When this value is set to true, the machine will 132 start without a console. For VMware machines, Packer will output VNC 133 connection information in case you need to connect to the console to 134 debug the build process. 135 136 * `http_directory` (string) - Path to a directory to serve using an HTTP 137 server. The files in this directory will be available over HTTP that will 138 be requestable from the virtual machine. This is useful for hosting 139 kickstart files and so on. By default this is "", which means no HTTP 140 server will be started. The address and port of the HTTP server will be 141 available as variables in `boot_command`. This is covered in more detail 142 below. 143 144 * `http_port_min` and `http_port_max` (integer) - These are the minimum and 145 maximum port to use for the HTTP server started to serve the `http_directory`. 146 Because Packer often runs in parallel, Packer will choose a randomly available 147 port in this range to run the HTTP server. If you want to force the HTTP 148 server to be on one port, make this minimum and maximum port the same. 149 By default the values are 8000 and 9000, respectively. 150 151 * `iso_urls` (array of strings) - Multiple URLs for the ISO to download. 152 Packer will try these in order. If anything goes wrong attempting to download 153 or while downloading a single URL, it will move on to the next. All URLs 154 must point to the same file (same checksum). By default this is empty 155 and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. 156 157 * `output_directory` (string) - This is the path to the directory where the 158 resulting virtual machine will be created. This may be relative or absolute. 159 If relative, the path is relative to the working directory when `packer` 160 is executed. This directory must not exist or be empty prior to running the builder. 161 By default this is "output-BUILDNAME" where "BUILDNAME" is the name 162 of the build. 163 164 * `remote_cache_datastore` (string) - The path to the datastore where 165 supporting files will be stored during the build on the remote machine. 166 By default this is the same as the `remote_datastore` option. This only 167 has an effect if `remote_type` is enabled. 168 169 * `remote_cache_directory` (string) - The path where the ISO and/or floppy 170 files will be stored during the build on the remote machine. The path is 171 relative to the `remote_cache_datastore` on the remote machine. By default 172 this is "packer_cache". This only has an effect if `remote_type` is enabled. 173 174 * `remote_datastore` (string) - The path to the datastore where the resulting 175 VM will be stored when it is built on the remote machine. By default this 176 is "datastore1". This only has an effect if `remote_type` is enabled. 177 178 * `remote_host` (string) - The host of the remote machine used for access. 179 This is only required if `remote_type` is enabled. 180 181 * `remote_password` (string) - The SSH password for the user used to 182 access the remote machine. By default this is empty. This only has an 183 effect if `remote_type` is enabled. 184 185 * `remote_type` (string) - The type of remote machine that will be used to 186 build this VM rather than a local desktop product. The only value accepted 187 for this currently is "esx5". If this is not set, a desktop product will be 188 used. By default, this is not set. 189 190 * `remote_username` (string) - The username for the SSH user that will access 191 the remote machine. This is required if `remote_type` is enabled. 192 193 * `shutdown_command` (string) - The command to use to gracefully shut down 194 the machine once all the provisioning is done. By default this is an empty 195 string, which tells Packer to just forcefully shut down the machine. 196 197 * `shutdown_timeout` (string) - The amount of time to wait after executing 198 the `shutdown_command` for the virtual machine to actually shut down. 199 If it doesn't shut down in this time, it is an error. By default, the timeout 200 is "5m", or five minutes. 201 202 * `skip_compaction` (boolean) - VMware-created disks are defragmented 203 and compacted at the end of the build process using `vmware-vdiskmanager`. 204 In certain rare cases, this might actually end up making the resulting disks 205 slightly larger. If you find this to be the case, you can disable compaction 206 using this configuration value. 207 208 * `tools_upload_flavor` (string) - The flavor of the VMware Tools ISO to 209 upload into the VM. Valid values are "darwin", "linux", and "windows". 210 By default, this is empty, which means VMware tools won't be uploaded. 211 212 * `tools_upload_path` (string) - The path in the VM to upload the VMware 213 tools. This only takes effect if `tools_upload_flavor` is non-empty. 214 This is a [configuration template](/docs/templates/configuration-templates.html) 215 that has a single valid variable: `Flavor`, which will be the value of 216 `tools_upload_flavor`. By default the upload path is set to 217 `{{.Flavor}}.iso`. This setting is not used when `remote_type` is "esx5". 218 219 * `version` (string) - The [vmx hardware version](http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1003746) for the new virtual machine. Only the default value has been tested, any other value is experimental. Default value is '9'. 220 221 * `vm_name` (string) - This is the name of the VMX file for the new virtual 222 machine, without the file extension. By default this is "packer-BUILDNAME", 223 where "BUILDNAME" is the name of the build. 224 225 * `vmdk_name` (string) - The filename of the virtual disk that'll be created, 226 without the extension. This defaults to "packer". 227 228 * `vmx_data` (object of key/value strings) - Arbitrary key/values 229 to enter into the virtual machine VMX file. This is for advanced users 230 who want to set properties such as memory, CPU, etc. 231 232 * `vmx_data_post` (object of key/value strings) - Identical to `vmx_data`, 233 except that it is run after the virtual machine is shutdown, and before the 234 virtual machine is exported. 235 236 * `vmx_template_path` (string) - Path to a 237 [configuration template](/docs/templates/configuration-templates.html) that 238 defines the contents of the virtual machine VMX file for VMware. This is 239 for **advanced users only** as this can render the virtual machine 240 non-functional. See below for more information. For basic VMX modifications, 241 try `vmx_data` first. 242 243 * `vnc_port_min` and `vnc_port_max` (integer) - The minimum and maximum port to 244 use for VNC access to the virtual machine. The builder uses VNC to type 245 the initial `boot_command`. Because Packer generally runs in parallel, Packer 246 uses a randomly chosen port in this range that appears available. By default 247 this is 5900 to 6000. The minimum and maximum ports are inclusive. 248 249 ## Boot Command 250 251 The `boot_command` configuration is very important: it specifies the keys 252 to type when the virtual machine is first booted in order to start the 253 OS installer. This command is typed after `boot_wait`, which gives the 254 virtual machine some time to actually load the ISO. 255 256 As documented above, the `boot_command` is an array of strings. The 257 strings are all typed in sequence. It is an array only to improve readability 258 within the template. 259 260 The boot command is "typed" character for character over a VNC connection 261 to the machine, simulating a human actually typing the keyboard. There are 262 a set of special keys available. If these are in your boot command, they 263 will be replaced by the proper key: 264 265 * `<bs>` - Backspace 266 267 * `<del>` - Delete 268 269 * `<enter>` and `<return>` - Simulates an actual "enter" or "return" keypress. 270 271 * `<esc>` - Simulates pressing the escape key. 272 273 * `<tab>` - Simulates pressing the tab key. 274 275 * `<f1>` - `<f12>` - Simulates pressing a function key. 276 277 * `<up>` `<down>` `<left>` `<right>` - Simulates pressing an arrow key. 278 279 * `<spacebar>` - Simulates pressing the spacebar. 280 281 * `<insert>` - Simulates pressing the insert key. 282 283 * `<home>` `<end>` - Simulates pressing the home and end keys. 284 285 * `<pageUp>` `<pageDown>` - Simulates pressing the page up and page down keys. 286 287 * `<wait>` `<wait5>` `<wait10>` - Adds a 1, 5 or 10 second pause before sending any additional keys. This 288 is useful if you have to generally wait for the UI to update before typing more. 289 290 In addition to the special keys, each command to type is treated as a 291 [configuration template](/docs/templates/configuration-templates.html). 292 The available variables are: 293 294 * `HTTPIP` and `HTTPPort` - The IP and port, respectively of an HTTP server 295 that is started serving the directory specified by the `http_directory` 296 configuration parameter. If `http_directory` isn't specified, these will 297 be blank! 298 299 Example boot command. This is actually a working boot command used to start 300 an Ubuntu 12.04 installer: 301 302 ```text 303 [ 304 "<esc><esc><enter><wait>", 305 "/install/vmlinuz noapic ", 306 "preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/preseed.cfg ", 307 "debian-installer=en_US auto locale=en_US kbd-chooser/method=us ", 308 "hostname={{ .Name }} ", 309 "fb=false debconf/frontend=noninteractive ", 310 "keyboard-configuration/modelcode=SKIP keyboard-configuration/layout=USA ", 311 "keyboard-configuration/variant=USA console-setup/ask_detect=false ", 312 "initrd=/install/initrd.gz -- <enter>" 313 ] 314 ``` 315 316 ## VMX Template 317 318 The heart of a VMware machine is the "vmx" file. This contains all the 319 virtual hardware metadata necessary for the VM to function. Packer by default 320 uses a [safe, flexible VMX file](https://github.com/mitchellh/packer/blob/20541a7eda085aa5cf35bfed5069592ca49d106e/builder/vmware/step_create_vmx.go#L84). 321 But for advanced users, this template can be customized. This allows 322 Packer to build virtual machines of effectively any guest operating system 323 type. 324 325 ~> **This is an advanced feature.** Modifying the VMX template 326 can easily cause your virtual machine to not boot properly. Please only 327 modify the template if you know what you're doing. 328 329 Within the template, a handful of variables are available so that your 330 template can continue working with the rest of the Packer machinery. Using 331 these variables isn't required, however. 332 333 * `Name` - The name of the virtual machine. 334 * `GuestOS` - The VMware-valid guest OS type. 335 * `DiskName` - The filename (without the suffix) of the main virtual disk. 336 * `ISOPath` - The path to the ISO to use for the OS installation. 337 * `Version` - The Hardware version VMWare will execute this vm under. Also known as the `virtualhw.version`. 338 339 ## Building on a Remote vSphere Hypervisor 340 341 In addition to using the desktop products of VMware locally to build 342 virtual machines, Packer can use a remote VMware Hypervisor to build 343 the virtual machine. 344 345 -> **Note:** Packer supports ESXi 5.1 and above. 346 347 Before using a remote vSphere Hypervisor, you need to enable GuestIPHack by running the following command: 348 349 ```text 350 esxcli system settings advanced set -o /Net/GuestIPHack -i 1 351 ``` 352 353 When using a remote VMware Hypervisor, the builder still downloads the 354 ISO and various files locally, and uploads these to the remote machine. 355 Packer currently uses SSH to communicate to the ESXi machine rather than 356 the vSphere API. At some point, the vSphere API may be used. 357 358 Packer also requires VNC to issue boot commands during a build, 359 which may be disabled on some remote VMware Hypervisors. Please consult 360 the appropriate documentation on how to update VMware Hypervisor's firewall 361 to allow these connections. 362 363 To use a remote VMware vSphere Hypervisor to build your virtual machine, 364 fill in the required `remote_*` configurations: 365 366 * `remote_type` - This must be set to "esx5". 367 368 * `remote_host` - The host of the remote machine. 369 370 Additionally, there are some optional configurations that you'll likely 371 have to modify as well: 372 373 * `remote_datastore` - The path to the datastore where the VM will be 374 stored on the ESXi machine. 375 376 * `remote_cache_datastore` - The path to the datastore where 377 supporting files will be stored during the build on the remote machine. 378 379 * `remote_cache_directory` - The path where the ISO and/or floppy 380 files will be stored during the build on the remote machine. The path is 381 relative to the `remote_cache_datastore` on the remote machine. 382 383 * `remote_username` - The SSH username used to access the remote machine. 384 385 * `remote_password` - The SSH password for access to the remote machine.