github.com/raghuse92/packer@v1.3.2/website/source/docs/builders/virtualbox-iso.html.md.erb (about) 1 --- 2 modeline: | 3 vim: set ft=pandoc: 4 description: | 5 The VirtualBox Packer builder is able to create VirtualBox virtual machines 6 and export them in the OVF format, starting from an ISO image. 7 layout: docs 8 page_title: 'VirtualBox ISO - Builders' 9 sidebar_current: 'docs-builders-virtualbox-iso' 10 --- 11 12 # VirtualBox Builder (from an ISO) 13 14 Type: `virtualbox-iso` 15 16 The VirtualBox Packer builder is able to create 17 [VirtualBox](https://www.virtualbox.org/) virtual machines and export them in 18 the OVF format, starting from an ISO image. 19 20 The builder builds a virtual machine by creating a new virtual machine from 21 scratch, booting it, installing an OS, provisioning software within the OS, then 22 shutting it down. The result of the VirtualBox builder is a directory containing 23 all the files necessary to run the virtual machine portably. 24 25 ## Basic Example 26 27 Here is a basic example. This example is not functional. It will start the OS 28 installer but then fail because we don't provide the preseed file for Ubuntu to 29 self-install. Still, the example serves to show the basic configuration: 30 31 ``` json 32 { 33 "type": "virtualbox-iso", 34 "guest_os_type": "Ubuntu_64", 35 "iso_url": "http://releases.ubuntu.com/12.04/ubuntu-12.04.5-server-amd64.iso", 36 "iso_checksum": "769474248a3897f4865817446f9a4a53", 37 "iso_checksum_type": "md5", 38 "ssh_username": "packer", 39 "ssh_password": "packer", 40 "shutdown_command": "echo 'packer' | sudo -S shutdown -P now" 41 } 42 ``` 43 44 It is important to add a `shutdown_command`. By default Packer halts the virtual 45 machine and the file system may not be sync'd. Thus, changes made in a 46 provisioner might not be saved. 47 48 ## Configuration Reference 49 50 There are many configuration options available for the VirtualBox builder. They 51 are organized below into two categories: required and optional. Within each 52 category, the available options are alphabetized and described. 53 54 In addition to the options listed here, a 55 [communicator](/docs/templates/communicator.html) can be configured for this 56 builder. 57 58 ### Required: 59 60 - `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO 61 files are so large, this is required and Packer will verify it prior to 62 booting a virtual machine with the ISO attached. The type of the checksum is 63 specified with `iso_checksum_type`, documented below. At least one of 64 `iso_checksum` and `iso_checksum_url` must be defined. This has precedence 65 over `iso_checksum_url` type. 66 67 - `iso_checksum_type` (string) - The type of the checksum specified in 68 `iso_checksum`. Valid values are `none`, `md5`, `sha1`, `sha256`, or 69 `sha512` currently. While `none` will skip checksumming, this is not 70 recommended since ISO files are generally large and corruption does happen 71 from time to time. 72 73 - `iso_checksum_url` (string) - A URL to a GNU or BSD style checksum file 74 containing a checksum for the OS ISO file. At least one of `iso_checksum` 75 and `iso_checksum_url` must be defined. This will be ignored if 76 `iso_checksum` is non empty. 77 78 - `iso_url` (string) - A URL to the ISO containing the installation image. 79 This URL can be either an HTTP URL or a file URL (or path to a file). If 80 this is an HTTP URL, Packer will download it and cache it between runs. 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 88 boot command. If this is not specified, it is assumed the installer will 89 start 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 95 specified, the default is `10s` or 10 seconds. 96 97 - `disk_size` (number) - The size, in megabytes, of the hard disk to create 98 for the VM. By default, this is `40000` (about 40 GB). 99 100 - `export_opts` (array of strings) - Additional options to pass to the 101 [VBoxManage 102 export](https://www.virtualbox.org/manual/ch08.html#vboxmanage-export). This 103 can be useful for passing product information to include in the resulting 104 appliance file. Packer JSON configuration file example: 105 106 ``` json 107 { 108 "type": "virtualbox-iso", 109 "export_opts": 110 [ 111 "--manifest", 112 "--vsys", "0", 113 "--description", "{{user `vm_description`}}", 114 "--version", "{{user `vm_version`}}" 115 ], 116 "format": "ova", 117 } 118 ``` 119 120 A VirtualBox [VM 121 description](https://www.virtualbox.org/manual/ch08.html#idm3756) may 122 contain arbitrary strings; the GUI interprets HTML formatting. However, the 123 JSON format does not allow arbitrary newlines within a value. Add a 124 multi-line description by preparing the string in the shell before the 125 packer call like this (shell `>` continuation character snipped for easier 126 copy & paste): 127 128 ``` {.shell} 129 130 vm_description='some 131 multiline 132 description' 133 134 vm_version='0.2.0' 135 136 packer build \ 137 -var "vm_description=${vm_description}" \ 138 -var "vm_version=${vm_version}" \ 139 "packer_conf.json" 140 ``` 141 142 - `floppy_dirs` (array of strings) - A list of directories to place onto 143 the floppy disk recursively. This is similar to the `floppy_files` option 144 except that the directory structure is preserved. This is useful for when 145 your floppy disk includes drivers or if you just want to organize it's 146 contents as a hierarchy. Wildcard characters (\*, ?, and \[\]) are allowed. 147 148 - `floppy_files` (array of strings) - A list of files to place onto a floppy 149 disk that is attached when the VM is booted. This is most useful for 150 unattended Windows installs, which look for an `Autounattend.xml` file on 151 removable media. By default, no floppy will be attached. All files listed in 152 this setting get placed into the root directory of the floppy and the floppy 153 is attached as the first floppy device. Currently, no support exists for 154 creating sub-directories on the floppy. Wildcard characters (\*, ?, 155 and \[\]) are allowed. Directory names are also allowed, which will add all 156 the files found in the directory to the floppy. 157 158 - `format` (string) - Either `ovf` or `ova`, this specifies the output format 159 of the exported virtual machine. This defaults to `ovf`. 160 161 - `guest_additions_mode` (string) - The method by which guest additions are 162 made available to the guest for installation. Valid options are `upload`, 163 `attach`, or `disable`. If the mode is `attach` the guest additions ISO will 164 be attached as a CD device to the virtual machine. If the mode is `upload` 165 the guest additions ISO will be uploaded to the path specified by 166 `guest_additions_path`. The default value is `upload`. If `disable` is used, 167 guest additions won't be downloaded, either. 168 169 - `guest_additions_path` (string) - The path on the guest virtual machine 170 where the VirtualBox guest additions ISO will be uploaded. By default this 171 is `VBoxGuestAdditions.iso` which should upload into the login directory of 172 the user. This is a [configuration 173 template](/docs/templates/engine.html) where the `Version` 174 variable is replaced with the VirtualBox version. 175 176 - `guest_additions_sha256` (string) - The SHA256 checksum of the guest 177 additions ISO that will be uploaded to the guest VM. By default the 178 checksums will be downloaded from the VirtualBox website, so this only needs 179 to be set if you want to be explicit about the checksum. 180 181 - `guest_additions_url` (string) - The URL to the guest additions ISO 182 to upload. This can also be a file URL if the ISO is at a local path. By 183 default, the VirtualBox builder will attempt to find the guest additions ISO 184 on the local file system. If it is not available locally, the builder will 185 download the proper guest additions ISO from the internet. 186 187 - `guest_os_type` (string) - The guest OS type being installed. By default 188 this is `other`, but you can get *dramatic* performance improvements by 189 setting this to the proper value. To view all available values for this run 190 `VBoxManage list ostypes`. Setting the correct value hints to VirtualBox how 191 to optimize the virtual hardware to work best with that operating system. 192 193 - `hard_drive_interface` (string) - The type of controller that the primary 194 hard drive is attached to, defaults to `ide`. When set to `sata`, the drive 195 is attached to an AHCI SATA controller. When set to `scsi`, the drive is 196 attached to an LsiLogic SCSI controller. 197 198 - `sata_port_count` (number) - The number of ports available on any SATA 199 controller created, defaults to `1`. VirtualBox supports up to 30 ports on a 200 maximum of 1 SATA controller. Increasing this value can be useful if you 201 want to attach additional drives. 202 203 - `hard_drive_nonrotational` (boolean) - Forces some guests (i.e. Windows 7+) 204 to treat disks as SSDs and stops them from performing disk fragmentation. 205 Also set `hard_drive_discard` to `true` to enable TRIM support. 206 207 - `hard_drive_discard` (boolean) - When this value is set to `true`, a VDI 208 image will be shrunk in response to the trim command from the guest OS. 209 The size of the cleared area must be at least 1MB. Also set 210 `hard_drive_nonrotational` to `true` to enable TRIM support. 211 212 - `headless` (boolean) - Packer defaults to building VirtualBox virtual 213 machines by launching a GUI that shows the console of the machine 214 being built. When this value is set to `true`, the machine will start 215 without a console. 216 217 - `http_directory` (string) - Path to a directory to serve using an 218 HTTP server. The files in this directory will be available over HTTP that 219 will be requestable from the virtual machine. This is useful for hosting 220 kickstart files and so on. By default this is an empty string, which means 221 no HTTP server will be started. The address and port of the HTTP server will 222 be available as variables in `boot_command`. This is covered in more detail 223 below. 224 225 - `http_port_min` and `http_port_max` (number) - These are the minimum and 226 maximum port to use for the HTTP server started to serve the 227 `http_directory`. Because Packer often runs in parallel, Packer will choose 228 a randomly available port in this range to run the HTTP server. If you want 229 to force the HTTP server to be on one port, make this minimum and maximum 230 port the same. By default the values are `8000` and `9000`, respectively. 231 232 - `iso_interface` (string) - The type of controller that the ISO is attached 233 to, defaults to `ide`. When set to `sata`, the drive is attached to an AHCI 234 SATA controller. 235 236 - `iso_target_extension` (string) - The extension of the iso file after 237 download. This defaults to `iso`. 238 239 - `iso_target_path` (string) - The path where the iso should be saved 240 after download. By default will go in the packer cache, with a hash of the 241 original filename as its name. 242 243 - `iso_urls` (array of strings) - Multiple URLs for the ISO to download. 244 Packer will try these in order. If anything goes wrong attempting to 245 download or while downloading a single URL, it will move on to the next. All 246 URLs must point to the same file (same checksum). By default this is empty 247 and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. 248 249 - `keep_registered` (boolean) - Set this to `true` if you would like to keep 250 the VM registered with virtualbox. Defaults to `false`. 251 252 - `output_directory` (string) - This is the path to the directory where the 253 resulting virtual machine will be created. This may be relative or absolute. 254 If relative, the path is relative to the working directory when `packer` 255 is executed. This directory must not exist or be empty prior to running 256 the builder. By default this is `output-BUILDNAME` where "BUILDNAME" is the 257 name of the build. 258 259 - `post_shutdown_delay` (string) - The amount of time to wait after shutting 260 down the virtual machine. If you get the error 261 `Error removing floppy controller`, you might need to set this to `5m` 262 or so. By default, the delay is `0s` or disabled. 263 264 - `shutdown_command` (string) - The command to use to gracefully shut down the 265 machine once all the provisioning is done. By default this is an empty 266 string, which tells Packer to just forcefully shut down the machine unless a 267 shutdown command takes place inside script so this may safely be omitted. If 268 one or more scripts require a reboot it is suggested to leave this blank 269 since reboots may fail and specify the final shutdown command in your 270 last script. 271 272 - `shutdown_timeout` (string) - The amount of time to wait after executing the 273 `shutdown_command` for the virtual machine to actually shut down. If it 274 doesn't shut down in this time, it is an error. By default, the timeout is 275 `5m` or five minutes. 276 277 - `skip_export` (boolean) - Defaults to `false`. When enabled, Packer will 278 not export the VM. Useful if the build output is not the resultant image, 279 but created inside the VM. 280 281 - `ssh_host_port_min` and `ssh_host_port_max` (number) - The minimum and 282 maximum port to use for the SSH port on the host machine which is forwarded 283 to the SSH port on the guest machine. Because Packer often runs in parallel, 284 Packer will choose a randomly available port in this range to use as the 285 host port. By default this is `2222` to `4444`. 286 287 - `ssh_skip_nat_mapping` (boolean) - Defaults to `false`. When enabled, Packer 288 does not setup forwarded port mapping for SSH requests and uses `ssh_port` 289 on the host to communicate to the virtual machine. 290 291 - `vboxmanage` (array of array of strings) - Custom `VBoxManage` commands to 292 execute in order to further customize the virtual machine being created. The 293 value of this is an array of commands to execute. The commands are executed 294 in the order defined in the template. For each command, the command is 295 defined itself as an array of strings, where each string represents a single 296 argument on the command-line to `VBoxManage` (but excluding 297 `VBoxManage` itself). Each arg is treated as a [configuration 298 template](/docs/templates/engine.html), where the `Name` 299 variable is replaced with the VM name. More details on how to use 300 `VBoxManage` are below. 301 302 - `vboxmanage_post` (array of array of strings) - Identical to `vboxmanage`, 303 except that it is run after the virtual machine is shutdown, and before the 304 virtual machine is exported. 305 306 - `virtualbox_version_file` (string) - The path within the virtual machine to 307 upload a file that contains the VirtualBox version that was used to create 308 the machine. This information can be useful for provisioning. By default 309 this is `.vbox_version`, which will generally be upload it into the 310 home directory. Set to an empty string to skip uploading this file, which 311 can be useful when using the `none` communicator. 312 313 - `vm_name` (string) - This is the name of the OVF file for the new virtual 314 machine, without the file extension. By default this is `packer-BUILDNAME`, 315 where "BUILDNAME" is the name of the build. 316 317 - `vrdp_bind_address` (string / IP address) - The IP address that should be 318 binded to for VRDP. By default packer will use `127.0.0.1` for this. If you 319 wish to bind to all interfaces use `0.0.0.0`. 320 321 - `vrdp_port_min` and `vrdp_port_max` (number) - The minimum and maximum port 322 to use for VRDP access to the virtual machine. Packer uses a randomly chosen 323 port in this range that appears available. By default this is `5900` to 324 `6000`. The minimum and maximum ports are inclusive. 325 326 ## Boot Command 327 328 The `boot_command` configuration is very important: it specifies the keys to 329 type when the virtual machine is first booted in order to start the OS 330 installer. This command is typed after `boot_wait`, which gives the virtual 331 machine some time to actually load the ISO. 332 333 As documented above, the `boot_command` is an array of strings. The strings are 334 all typed in sequence. It is an array only to improve readability within the 335 template. 336 337 The boot command is sent to the VM through the `VBoxManage` utility in as few 338 invocations as possible. We send each character in groups of 25, with a default 339 delay of 100ms between groups. The delay alleviates issues with latency and CPU 340 contention. If you notice missing keys, you can tune this delay by specifying 341 "boot_keygroup_interval" in your Packer template, for example: 342 343 ``` 344 { 345 "builders": [ 346 { 347 "type": "virtualbox", 348 "boot_keygroup_interval": "500ms" 349 ... 350 } 351 ] 352 } 353 ``` 354 355 <%= partial "partials/builders/boot-command" %> 356 357 Example boot command. This is actually a working boot command used to start an 358 Ubuntu 12.04 installer: 359 360 ``` text 361 [ 362 "<esc><esc><enter><wait>", 363 "/install/vmlinuz noapic ", 364 "preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/preseed.cfg ", 365 "debian-installer=en_US auto locale=en_US kbd-chooser/method=us ", 366 "hostname={{ .Name }} ", 367 "fb=false debconf/frontend=noninteractive ", 368 "keyboard-configuration/modelcode=SKIP keyboard-configuration/layout=USA ", 369 "keyboard-configuration/variant=USA console-setup/ask_detect=false ", 370 "initrd=/install/initrd.gz -- <enter>" 371 ] 372 ``` 373 374 For more examples of various boot commands, see the sample projects from our 375 [community templates page](/community-tools.html#templates). 376 377 ## Guest Additions 378 379 Packer will automatically download the proper guest additions for the version of 380 VirtualBox that is running and upload those guest additions into the virtual 381 machine so that provisioners can easily install them. 382 383 Packer downloads the guest additions from the official VirtualBox website, and 384 verifies the file with the official checksums released by VirtualBox. 385 386 After the virtual machine is up and the operating system is installed, Packer 387 uploads the guest additions into the virtual machine. The path where they are 388 uploaded is controllable by `guest_additions_path`, and defaults to 389 "VBoxGuestAdditions.iso". Without an absolute path, it is uploaded to the home 390 directory of the SSH user. 391 392 ## VBoxManage Commands 393 394 In order to perform extra customization of the virtual machine, a template can 395 define extra calls to `VBoxManage` to perform. 396 [VBoxManage](https://www.virtualbox.org/manual/ch08.html) is the command-line 397 interface to VirtualBox where you can completely control VirtualBox. It can be 398 used to do things such as set RAM, CPUs, etc. 399 400 Extra VBoxManage commands are defined in the template in the `vboxmanage` 401 section. An example is shown below that sets the memory and number of CPUs 402 within the virtual machine: 403 404 ``` json 405 { 406 "vboxmanage": [ 407 ["modifyvm", "{{.Name}}", "--memory", "1024"], 408 ["modifyvm", "{{.Name}}", "--cpus", "2"] 409 ] 410 } 411 ``` 412 413 The value of `vboxmanage` is an array of commands to execute. These commands are 414 executed in the order defined. So in the above example, the memory will be set 415 followed by the CPUs. 416 417 Each command itself is an array of strings, where each string is an argument to 418 `VBoxManage`. Each argument is treated as a [configuration 419 template](/docs/templates/engine.html). The only available 420 variable is `Name` which is replaced with the unique name of the VM, which is 421 required for many VBoxManage calls.