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