github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/builders/parallels-iso.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "Parallels Builder (from an ISO)" 4 description: |- 5 The Parallels Packer builder is able to create Parallels Desktop for Mac virtual machines and export them in the PVM format, starting from an ISO image. 6 --- 7 8 # Parallels Builder (from an ISO) 9 10 Type: `parallels-iso` 11 12 The Parallels Packer builder is able to create 13 [Parallels Desktop for Mac](http://www.parallels.com/products/desktop/) virtual 14 machines and export them in the PVM format, starting from an 15 ISO image. 16 17 The builder builds a virtual machine by creating a new virtual machine 18 from scratch, booting it, installing an OS, provisioning software within 19 the OS, then shutting it down. The result of the Parallels builder is a directory 20 containing all the files necessary to run the virtual machine portably. 21 22 ## Basic Example 23 24 Here is a basic example. This example is not functional. It will start the 25 OS installer but then fail because we don't provide the preseed file for 26 Ubuntu to self-install. Still, the example serves to show the basic configuration: 27 28 ```javascript 29 { 30 "type": "parallels-iso", 31 "guest_os_type": "ubuntu", 32 "iso_url": "http://releases.ubuntu.com/12.04/ubuntu-12.04.3-server-amd64.iso", 33 "iso_checksum": "2cbe868812a871242cdcdd8f2fd6feb9", 34 "iso_checksum_type": "md5", 35 "parallels_tools_flavor": "lin", 36 "ssh_username": "packer", 37 "ssh_password": "packer", 38 "ssh_wait_timeout": "30s", 39 "shutdown_command": "echo 'packer' | sudo -S shutdown -P now" 40 } 41 ``` 42 43 It is important to add a `shutdown_command`. By default Packer halts the 44 virtual machine and the file system may not be sync'd. Thus, changes made in a 45 provisioner might not be saved. 46 47 ## Configuration Reference 48 49 There are many configuration options available for the Parallels builder. 50 They are organized below into two categories: required and optional. Within 51 each category, the available options are alphabetized and described. 52 53 In addition to the options listed here, a 54 [communicator](/docs/templates/communicator.html) 55 can be configured for this builder. 56 57 ### Required: 58 59 * `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO 60 files are so large, this is required and Packer will verify it prior 61 to booting a virtual machine with the ISO attached. The type of the 62 checksum is specified with `iso_checksum_type`, documented below. 63 64 * `iso_checksum_type` (string) - The type of the checksum specified in 65 `iso_checksum`. Valid values are "none", "md5", "sha1", "sha256", or 66 "sha512" currently. While "none" will skip checksumming, this is not 67 recommended since ISO files are generally large and corruption does happen 68 from time to time. 69 70 * `iso_url` (string) - A URL to the ISO containing the installation image. 71 This URL can be either an HTTP URL or a file URL (or path to a file). 72 If this is an HTTP URL, Packer will download it and cache it between 73 runs. 74 75 * `ssh_username` (string) - The username to use to SSH into the machine 76 once the OS is installed. 77 78 * `parallels_tools_flavor` (string) - The flavor of the Parallels Tools ISO to 79 install into the VM. Valid values are "win", "lin", "mac", "os2" and "other". 80 This can be omitted only if `parallels_tools_mode` is "disable". 81 82 ### Optional: 83 84 * `boot_command` (array of strings) - This is an array of commands to type 85 when the virtual machine is first booted. The goal of these commands should 86 be to type just enough to initialize the operating system installer. Special 87 keys can be typed as well, and are covered in the section below on the boot 88 command. If this is not specified, it is assumed the installer will start 89 itself. 90 91 * `boot_wait` (string) - The time to wait after booting the initial virtual 92 machine before typing the `boot_command`. The value of this should be 93 a duration. Examples are "5s" and "1m30s" which will cause Packer to wait 94 five seconds and one minute 30 seconds, respectively. If this isn't specified, 95 the default is 10 seconds. 96 97 * `disk_size` (integer) - The size, in megabytes, of the hard disk to create 98 for the VM. By default, this is 40000 (about 40 GB). 99 100 * `floppy_files` (array of strings) - A list of files to place onto a floppy 101 disk that is attached when the VM is booted. This is most useful 102 for unattended Windows installs, which look for an `Autounattend.xml` file 103 on removable media. By default, no floppy will be attached. All files 104 listed in this setting get placed into the root directory of the floppy 105 and the floppy is attached as the first floppy device. Currently, no 106 support exists for creating sub-directories on the floppy. Wildcard 107 characters (*, ?, and []) are allowed. Directory names are also allowed, 108 which will add all the files found in the directory to the floppy. 109 110 * `guest_os_type` (string) - The guest OS type being installed. By default 111 this is "other", but you can get _dramatic_ performance improvements by 112 setting this to the proper value. To view all available values for this 113 run `prlctl create x --distribution list`. Setting the correct value hints to 114 Parallels Desktop how to optimize the virtual hardware to work best with 115 that operating system. 116 117 * `hard_drive_interface` (string) - The type of controller that the 118 hard drives are attached to, defaults to "sata". Valid options are 119 "sata", "ide", and "scsi". 120 121 * `host_interfaces` (array of strings) - A list of which interfaces on the 122 host should be searched for a IP address. The first IP address found on 123 one of these will be used as `{{ .HTTPIP }}` in the `boot_command`. 124 Defaults to ["en0", "en1", "en2", "en3", "en4", "en5", "en6", "en7", "en8", 125 "en9", "ppp0", "ppp1", "ppp2"]. 126 127 * `http_directory` (string) - Path to a directory to serve using an HTTP 128 server. The files in this directory will be available over HTTP that will 129 be requestable from the virtual machine. This is useful for hosting 130 kickstart files and so on. By default this is "", which means no HTTP 131 server will be started. The address and port of the HTTP server will be 132 available as variables in `boot_command`. This is covered in more detail 133 below. 134 135 * `http_port_min` and `http_port_max` (integer) - These are the minimum and 136 maximum port to use for the HTTP server started to serve the `http_directory`. 137 Because Packer often runs in parallel, Packer will choose a randomly available 138 port in this range to run the HTTP server. If you want to force the HTTP 139 server to be on one port, make this minimum and maximum port the same. 140 By default the values are 8000 and 9000, respectively. 141 142 * `iso_urls` (array of strings) - Multiple URLs for the ISO to download. 143 Packer will try these in order. If anything goes wrong attempting to download 144 or while downloading a single URL, it will move on to the next. All URLs 145 must point to the same file (same checksum). By default this is empty 146 and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. 147 148 * `output_directory` (string) - This is the path to the directory where the 149 resulting virtual machine will be created. This may be relative or absolute. 150 If relative, the path is relative to the working directory when `packer` 151 is executed. This directory must not exist or be empty prior to running the builder. 152 By default this is "output-BUILDNAME" where "BUILDNAME" is the name 153 of the build. 154 155 * `parallels_tools_guest_path` (string) - The path in the virtual machine to upload 156 Parallels Tools. This only takes effect if `parallels_tools_mode` is "upload". 157 This is a [configuration template](/docs/templates/configuration-templates.html) 158 that has a single valid variable: `Flavor`, which will be the value of 159 `parallels_tools_flavor`. By default this is "prl-tools-{{.Flavor}}.iso" which 160 should upload into the login directory of the user. 161 162 * `parallels_tools_mode` (string) - The method by which Parallels Tools are made 163 available to the guest for installation. Valid options are "upload", "attach", 164 or "disable". If the mode is "attach" the Parallels Tools ISO will be attached 165 as a CD device to the virtual machine. If the mode is "upload" the Parallels 166 Tools ISO will be uploaded to the path specified by 167 `parallels_tools_guest_path`. The default value is "upload". 168 169 * `prlctl` (array of array of strings) - Custom `prlctl` commands to execute in 170 order to further customize the virtual machine being created. The value of 171 this is an array of commands to execute. The commands are executed in the order 172 defined in the template. For each command, the command is defined itself as an 173 array of strings, where each string represents a single argument on the 174 command-line to `prlctl` (but excluding `prlctl` itself). Each arg is treated 175 as a [configuration template](/docs/templates/configuration-templates.html), 176 where the `Name` variable is replaced with the VM name. More details on how 177 to use `prlctl` are below. 178 179 * `prlctl_post` (array of array of strings) - Identical to `prlctl`, 180 except that it is run after the virtual machine is shutdown, and before the 181 virtual machine is exported. 182 183 * `prlctl_version_file` (string) - The path within the virtual machine to upload 184 a file that contains the `prlctl` version that was used to create the machine. 185 This information can be useful for provisioning. By default this is 186 ".prlctl_version", which will generally upload it into the home directory. 187 188 * `shutdown_command` (string) - The command to use to gracefully shut down 189 the machine once all the provisioning is done. By default this is an empty 190 string, which tells Packer to just forcefully shut down the machine. 191 192 * `shutdown_timeout` (string) - The amount of time to wait after executing 193 the `shutdown_command` for the virtual machine to actually shut down. 194 If it doesn't shut down in this time, it is an error. By default, the timeout 195 is "5m", or five minutes. 196 197 * `vm_name` (string) - This is the name of the PVM directory for the new 198 virtual machine, without the file extension. By default this is 199 "packer-BUILDNAME", where "BUILDNAME" is the name of the build. 200 201 ## Boot Command 202 203 The `boot_command` configuration is very important: it specifies the keys 204 to type when the virtual machine is first booted in order to start the 205 OS installer. This command is typed after `boot_wait`, which gives the 206 virtual machine some time to actually load the ISO. 207 208 As documented above, the `boot_command` is an array of strings. The 209 strings are all typed in sequence. It is an array only to improve readability 210 within the template. 211 212 The boot command is "typed" character for character (using the Parallels 213 Virtualization SDK, see [Parallels Builder](/docs/builders/parallels.html)) 214 simulating a human actually typing the keyboard. There are a set of special 215 keys available. If these are in your boot command, they will be replaced by 216 the proper key: 217 218 * `<bs>` - Backspace 219 220 * `<del>` - Delete 221 222 * `<enter>` and `<return>` - Simulates an actual "enter" or "return" keypress. 223 224 * `<esc>` - Simulates pressing the escape key. 225 226 * `<tab>` - Simulates pressing the tab key. 227 228 * `<f1>` - `<f12>` - Simulates pressing a function key. 229 230 * `<up>` `<down>` `<left>` `<right>` - Simulates pressing an arrow key. 231 232 * `<spacebar>` - Simulates pressing the spacebar. 233 234 * `<insert>` - Simulates pressing the insert key. 235 236 * `<home>` `<end>` - Simulates pressing the home and end keys. 237 238 * `<pageUp>` `<pageDown>` - Simulates pressing the page up and page down keys. 239 240 * `<wait>` `<wait5>` `<wait10>` - Adds a 1, 5 or 10 second pause before sending any additional keys. This 241 is useful if you have to generally wait for the UI to update before typing more. 242 243 In addition to the special keys, each command to type is treated as a 244 [configuration template](/docs/templates/configuration-templates.html). 245 The available variables are: 246 247 * `HTTPIP` and `HTTPPort` - The IP and port, respectively of an HTTP server 248 that is started serving the directory specified by the `http_directory` 249 configuration parameter. If `http_directory` isn't specified, these will 250 be blank! 251 252 Example boot command. This is actually a working boot command used to start 253 an Ubuntu 12.04 installer: 254 255 ```text 256 [ 257 "<esc><esc><enter><wait>", 258 "/install/vmlinuz noapic ", 259 "preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/preseed.cfg ", 260 "debian-installer=en_US auto locale=en_US kbd-chooser/method=us ", 261 "hostname={{ .Name }} ", 262 "fb=false debconf/frontend=noninteractive ", 263 "keyboard-configuration/modelcode=SKIP keyboard-configuration/layout=USA ", 264 "keyboard-configuration/variant=USA console-setup/ask_detect=false ", 265 "initrd=/install/initrd.gz -- <enter>;" 266 ] 267 ``` 268 269 ## prlctl Commands 270 In order to perform extra customization of the virtual machine, a template can 271 define extra calls to `prlctl` to perform. 272 [prlctl](http://download.parallels.com/desktop/v9/ga/docs/en_US/Parallels%20Command%20Line%20Reference%20Guide.pdf) 273 is the command-line interface to Parallels Desktop. It can be used to configure 274 the virtual machine, such as set RAM, CPUs, etc. 275 276 Extra `prlctl` commands are defined in the template in the `prlctl` section. 277 An example is shown below that sets the memory and number of CPUs within the 278 virtual machine: 279 280 ```javascript 281 { 282 "prlctl": [ 283 ["set", "{{.Name}}", "--memsize", "1024"], 284 ["set", "{{.Name}}", "--cpus", "2"] 285 ] 286 } 287 ``` 288 289 The value of `prlctl` is an array of commands to execute. These commands are 290 executed in the order defined. So in the above example, the memory will be set 291 followed by the CPUs. 292 293 Each command itself is an array of strings, where each string is an argument to 294 `prlctl`. Each argument is treated as a 295 [configuration template](/docs/templates/configuration-templates.html). The only 296 available variable is `Name` which is replaced with the unique name of the VM, 297 which is required for many `prlctl` calls.