github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/builders/virtualbox-iso.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "VirtualBox Builder (from an ISO)" 4 description: |- 5 The VirtualBox Packer builder is able to create VirtualBox virtual machines and export them in the OVF format, starting from an ISO image. 6 --- 7 8 # VirtualBox Builder (from an ISO) 9 10 Type: `virtualbox-iso` 11 12 The VirtualBox Packer builder is able to create [VirtualBox](https://www.virtualbox.org/) 13 virtual machines and export them in the OVF format, starting from an 14 ISO image. 15 16 The builder builds a virtual machine by creating a new virtual machine 17 from scratch, booting it, installing an OS, provisioning software within 18 the OS, then shutting it down. The result of the VirtualBox builder is a directory 19 containing all the files necessary to run the virtual machine portably. 20 21 ## Basic Example 22 23 Here is a basic example. This example is not functional. It will start the 24 OS installer but then fail because we don't provide the preseed file for 25 Ubuntu to self-install. Still, the example serves to show the basic configuration: 26 27 ```javascript 28 { 29 "type": "virtualbox-iso", 30 "guest_os_type": "Ubuntu_64", 31 "iso_url": "http://releases.ubuntu.com/12.04/ubuntu-12.04.5-server-amd64.iso", 32 "iso_checksum": "769474248a3897f4865817446f9a4a53", 33 "iso_checksum_type": "md5", 34 "ssh_username": "packer", 35 "ssh_password": "packer", 36 "ssh_wait_timeout": "30s", 37 "shutdown_command": "echo 'packer' | sudo -S shutdown -P now" 38 } 39 ``` 40 41 It is important to add a `shutdown_command`. By default Packer halts the 42 virtual machine and the file system may not be sync'd. Thus, changes made in a 43 provisioner might not be saved. 44 45 ## Configuration Reference 46 47 There are many configuration options available for the VirtualBox builder. 48 They are organized below into two categories: required and optional. Within 49 each category, the available options are alphabetized and described. 50 51 In addition to the options listed here, a 52 [communicator](/docs/templates/communicator.html) 53 can be configured for this builder. 54 55 ### Required: 56 57 * `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO 58 files are so large, this is required and Packer will verify it prior 59 to booting a virtual machine with the ISO attached. The type of the 60 checksum is specified with `iso_checksum_type`, documented below. 61 62 * `iso_checksum_type` (string) - The type of the checksum specified in 63 `iso_checksum`. Valid values are "none", "md5", "sha1", "sha256", or 64 "sha512" currently. While "none" will skip checksumming, this is not 65 recommended since ISO files are generally large and corruption does happen 66 from time to time. 67 68 * `iso_url` (string) - A URL to the ISO containing the installation image. 69 This URL can be either an HTTP URL or a file URL (or path to a file). 70 If this is an HTTP URL, Packer will download it and cache it between 71 runs. 72 73 * `ssh_username` (string) - The username to use to SSH into the machine 74 once the OS is installed. 75 76 ### Optional: 77 78 * `boot_command` (array of strings) - This is an array of commands to type 79 when the virtual machine is first booted. The goal of these commands should 80 be to type just enough to initialize the operating system installer. Special 81 keys can be typed as well, and are covered in the section below on the boot 82 command. If this is not specified, it is assumed the installer will start 83 itself. 84 85 * `boot_wait` (string) - The time to wait after booting the initial virtual 86 machine before typing the `boot_command`. The value of this should be 87 a duration. Examples are "5s" and "1m30s" which will cause Packer to wait 88 five seconds and one minute 30 seconds, respectively. If this isn't specified, 89 the default is 10 seconds. 90 91 * `disk_size` (integer) - The size, in megabytes, of the hard disk to create 92 for the VM. By default, this is 40000 (about 40 GB). 93 94 * `export_opts` (array of strings) - Additional options to pass to the `VBoxManage export`. 95 This can be useful for passing product information to include in the resulting 96 appliance file. 97 98 * `floppy_files` (array of strings) - A list of files to place onto a floppy 99 disk that is attached when the VM is booted. This is most useful 100 for unattended Windows installs, which look for an `Autounattend.xml` file 101 on removable media. By default, no floppy will be attached. All files 102 listed in this setting get placed into the root directory of the floppy 103 and the floppy is attached as the first floppy device. Currently, no 104 support exists for creating sub-directories on the floppy. Wildcard 105 characters (*, ?, and []) are allowed. Directory names are also allowed, 106 which will add all the files found in the directory to the floppy. 107 108 * `format` (string) - Either "ovf" or "ova", this specifies the output 109 format of the exported virtual machine. This defaults to "ovf". 110 111 * `guest_additions_mode` (string) - The method by which guest additions 112 are made available to the guest for installation. Valid options are 113 "upload", "attach", or "disable". If the mode is "attach" the guest 114 additions ISO will be attached as a CD device to the virtual machine. 115 If the mode is "upload" the guest additions ISO will be uploaded to 116 the path specified by `guest_additions_path`. The default value is 117 "upload". If "disable" is used, guest additions won't be downloaded, 118 either. 119 120 * `guest_additions_path` (string) - The path on the guest virtual machine 121 where the VirtualBox guest additions ISO will be uploaded. By default this 122 is "VBoxGuestAdditions.iso" which should upload into the login directory 123 of the user. This is a [configuration template](/docs/templates/configuration-templates.html) 124 where the `Version` variable is replaced with the VirtualBox version. 125 126 * `guest_additions_sha256` (string) - The SHA256 checksum of the guest 127 additions ISO that will be uploaded to the guest VM. By default the 128 checksums will be downloaded from the VirtualBox website, so this only 129 needs to be set if you want to be explicit about the checksum. 130 131 * `guest_additions_url` (string) - The URL to the guest additions ISO 132 to upload. This can also be a file URL if the ISO is at a local path. 133 By default, the VirtualBox builder will attempt to find the guest additions 134 ISO on the local file system. If it is not available locally, the builder 135 will download the proper guest additions ISO from the internet. 136 137 * `guest_os_type` (string) - The guest OS type being installed. By default 138 this is "other", but you can get _dramatic_ performance improvements by 139 setting this to the proper value. To view all available values for this 140 run `VBoxManage list ostypes`. Setting the correct value hints to VirtualBox 141 how to optimize the virtual hardware to work best with that operating 142 system. 143 144 * `hard_drive_interface` (string) - The type of controller that the primary 145 hard drive is attached to, defaults to "ide". When set to "sata", the 146 drive is attached to an AHCI SATA controller. When set to "scsi", the drive 147 is attached to an LsiLogic SCSI controller. 148 149 * `headless` (boolean) - Packer defaults to building VirtualBox 150 virtual machines by launching a GUI that shows the console of the 151 machine being built. When this value is set to true, the machine will 152 start without a console. 153 154 * `http_directory` (string) - Path to a directory to serve using an HTTP 155 server. The files in this directory will be available over HTTP that will 156 be requestable from the virtual machine. This is useful for hosting 157 kickstart files and so on. By default this is "", which means no HTTP 158 server will be started. The address and port of the HTTP server will be 159 available as variables in `boot_command`. This is covered in more detail 160 below. 161 162 * `http_port_min` and `http_port_max` (integer) - These are the minimum and 163 maximum port to use for the HTTP server started to serve the `http_directory`. 164 Because Packer often runs in parallel, Packer will choose a randomly available 165 port in this range to run the HTTP server. If you want to force the HTTP 166 server to be on one port, make this minimum and maximum port the same. 167 By default the values are 8000 and 9000, respectively. 168 169 * `iso_interface` (string) - The type of controller that the ISO is attached 170 to, defaults to "ide". When set to "sata", the drive is attached to an 171 AHCI SATA controller. 172 173 * `iso_urls` (array of strings) - Multiple URLs for the ISO to download. 174 Packer will try these in order. If anything goes wrong attempting to download 175 or while downloading a single URL, it will move on to the next. All URLs 176 must point to the same file (same checksum). By default this is empty 177 and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. 178 179 * `output_directory` (string) - This is the path to the directory where the 180 resulting virtual machine will be created. This may be relative or absolute. 181 If relative, the path is relative to the working directory when `packer` 182 is executed. This directory must not exist or be empty prior to running the builder. 183 By default this is "output-BUILDNAME" where "BUILDNAME" is the name 184 of the build. 185 186 * `shutdown_command` (string) - The command to use to gracefully shut down the machine once all 187 the provisioning is done. By default this is an empty string, which tells Packer to just 188 forcefully shut down the machine unless a shutdown command takes place inside script so this may 189 safely be omitted. If one or more scripts require a reboot it is suggested to leave this blank 190 since reboots may fail and specify the final shutdown command in your last script. 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 * `ssh_host_port_min` and `ssh_host_port_max` (integer) - The minimum and 198 maximum port to use for the SSH port on the host machine which is forwarded 199 to the SSH port on the guest machine. Because Packer often runs in parallel, 200 Packer will choose a randomly available port in this range to use as the 201 host port. 202 203 * `ssh_skip_nat_mapping` (bool) - Defaults to false. When enabled, Packer does 204 not setup forwarded port mapping for SSH requests and uses `ssh_port` on the 205 host to communicate to the virtual machine 206 207 * `vboxmanage` (array of array of strings) - Custom `VBoxManage` commands to 208 execute in order to further customize the virtual machine being created. 209 The value of this is an array of commands to execute. The commands are executed 210 in the order defined in the template. For each command, the command is 211 defined itself as an array of strings, where each string represents a single 212 argument on the command-line to `VBoxManage` (but excluding `VBoxManage` 213 itself). Each arg is treated as a [configuration template](/docs/templates/configuration-templates.html), 214 where the `Name` variable is replaced with the VM name. More details on how 215 to use `VBoxManage` are below. 216 217 * `vboxmanage_post` (array of array of strings) - Identical to `vboxmanage`, 218 except that it is run after the virtual machine is shutdown, and before the 219 virtual machine is exported. 220 221 * `virtualbox_version_file` (string) - The path within the virtual machine 222 to upload a file that contains the VirtualBox version that was used to 223 create the machine. This information can be useful for provisioning. 224 By default this is ".vbox_version", which will generally be upload it into 225 the home directory. 226 227 * `vm_name` (string) - This is the name of the OVF file for the new virtual 228 machine, without the file extension. By default this is "packer-BUILDNAME", 229 where "BUILDNAME" is the name of the build. 230 231 ## Boot Command 232 233 The `boot_command` configuration is very important: it specifies the keys 234 to type when the virtual machine is first booted in order to start the 235 OS installer. This command is typed after `boot_wait`, which gives the 236 virtual machine some time to actually load the ISO. 237 238 As documented above, the `boot_command` is an array of strings. The 239 strings are all typed in sequence. It is an array only to improve readability 240 within the template. 241 242 The boot command is "typed" character for character over a VNC connection 243 to the machine, simulating a human actually typing the keyboard. There are 244 a set of special keys available. If these are in your boot command, they 245 will be replaced by the proper key: 246 247 * `<bs>` - Backspace 248 249 * `<del>` - Delete 250 251 * `<enter>` and `<return>` - Simulates an actual "enter" or "return" keypress. 252 253 * `<esc>` - Simulates pressing the escape key. 254 255 * `<tab>` - Simulates pressing the tab key. 256 257 * `<f1>` - `<f12>` - Simulates pressing a function key. 258 259 * `<up>` `<down>` `<left>` `<right>` - Simulates pressing an arrow key. 260 261 * `<spacebar>` - Simulates pressing the spacebar. 262 263 * `<insert>` - Simulates pressing the insert key. 264 265 * `<home>` `<end>` - Simulates pressing the home and end keys. 266 267 * `<pageUp>` `<pageDown>` - Simulates pressing the page up and page down keys. 268 269 * `<wait>` `<wait5>` `<wait10>` - Adds a 1, 5 or 10 second pause before sending any additional keys. This 270 is useful if you have to generally wait for the UI to update before typing more. 271 272 In addition to the special keys, each command to type is treated as a 273 [configuration template](/docs/templates/configuration-templates.html). 274 The available variables are: 275 276 * `HTTPIP` and `HTTPPort` - The IP and port, respectively of an HTTP server 277 that is started serving the directory specified by the `http_directory` 278 configuration parameter. If `http_directory` isn't specified, these will 279 be blank! 280 281 Example boot command. This is actually a working boot command used to start 282 an Ubuntu 12.04 installer: 283 284 ```text 285 [ 286 "<esc><esc><enter><wait>", 287 "/install/vmlinuz noapic ", 288 "preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/preseed.cfg ", 289 "debian-installer=en_US auto locale=en_US kbd-chooser/method=us ", 290 "hostname={{ .Name }} ", 291 "fb=false debconf/frontend=noninteractive ", 292 "keyboard-configuration/modelcode=SKIP keyboard-configuration/layout=USA ", 293 "keyboard-configuration/variant=USA console-setup/ask_detect=false ", 294 "initrd=/install/initrd.gz -- <enter>" 295 ] 296 ``` 297 298 ## Guest Additions 299 300 Packer will automatically download the proper guest additions for the 301 version of VirtualBox that is running and upload those guest additions into 302 the virtual machine so that provisioners can easily install them. 303 304 Packer downloads the guest additions from the official VirtualBox website, 305 and verifies the file with the official checksums released by VirtualBox. 306 307 After the virtual machine is up and the operating system is installed, 308 Packer uploads the guest additions into the virtual machine. The path where 309 they are uploaded is controllable by `guest_additions_path`, and defaults 310 to "VBoxGuestAdditions.iso". Without an absolute path, it is uploaded to the 311 home directory of the SSH user. 312 313 ## VBoxManage Commands 314 315 In order to perform extra customization of the virtual machine, a template 316 can define extra calls to `VBoxManage` to perform. [VBoxManage](http://www.virtualbox.org/manual/ch08.html) 317 is the command-line interface to VirtualBox where you can completely control 318 VirtualBox. It can be used to do things such as set RAM, CPUs, etc. 319 320 Extra VBoxManage commands are defined in the template in the `vboxmanage` section. 321 An example is shown below that sets the memory and number of CPUs within the 322 virtual machine: 323 324 ```javascript 325 { 326 "vboxmanage": [ 327 ["modifyvm", "{{.Name}}", "--memory", "1024"], 328 ["modifyvm", "{{.Name}}", "--cpus", "2"] 329 ] 330 } 331 ``` 332 333 The value of `vboxmanage` is an array of commands to execute. These commands 334 are executed in the order defined. So in the above example, the memory will be 335 set followed by the CPUs. 336 337 Each command itself is an array of strings, where each string is an argument 338 to `VBoxManage`. Each argument is treated as a 339 [configuration template](/docs/templates/configuration-templates.html). 340 The only available variable is `Name` which is replaced with the unique 341 name of the VM, which is required for many VBoxManage calls.