github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/builders/virtualbox-ovf.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "VirtualBox Builder (from an OVF/OVA)" 4 description: |- 5 This VirtualBox Packer builder is able to create VirtualBox virtual machines and export them in the OVF format, starting from an existing OVF/OVA (exported virtual machine image). 6 --- 7 8 # VirtualBox Builder (from an OVF/OVA) 9 10 Type: `virtualbox-ovf` 11 12 This 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 existing OVF/OVA (exported virtual machine image). 15 16 When exporting from VirtualBox make sure to choose OVF Version 2, since Version 1 is not compatible and will generate errors like this: 17 18 ``` 19 ==> virtualbox-ovf: Progress state: VBOX_E_FILE_ERROR 20 ==> virtualbox-ovf: VBoxManage: error: Appliance read failed 21 ==> virtualbox-ovf: VBoxManage: error: Error reading "source.ova": element "Section" has no "type" attribute, line 21 22 ==> virtualbox-ovf: VBoxManage: error: Details: code VBOX_E_FILE_ERROR (0x80bb0004), component Appliance, interface IAppliance 23 ==> virtualbox-ovf: VBoxManage: error: Context: "int handleImportAppliance(HandlerArg*)" at line 304 of file VBoxManageAppliance.cpp 24 ``` 25 26 The builder builds a virtual machine by importing an existing OVF or OVA 27 file. It then boots this image, runs provisioners on this new VM, and 28 exports that VM to create the image. The imported machine is deleted prior 29 to finishing the build. 30 31 ## Basic Example 32 33 Here is a basic example. This example is functional if you have an OVF matching 34 the settings here. 35 36 ```javascript 37 { 38 "type": "virtualbox-ovf", 39 "source_path": "source.ovf", 40 "ssh_username": "packer", 41 "ssh_password": "packer", 42 "ssh_wait_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 48 virtual 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 VirtualBox builder. 54 They are organized below into two categories: required and optional. Within 55 each category, the available options are alphabetized and described. 56 57 In addition to the options listed here, a 58 [communicator](/docs/templates/communicator.html) 59 can be configured for this builder. 60 61 ### Required: 62 63 * `source_path` (string) - The path to an OVF or OVA file that acts as 64 the source of this build. 65 66 * `ssh_username` (string) - The username to use to SSH into the machine 67 once the OS is installed. 68 69 ### Optional: 70 71 * `boot_command` (array of strings) - This is an array of commands to type 72 when the virtual machine is first booted. The goal of these commands should 73 be to type just enough to initialize the operating system installer. Special 74 keys can be typed as well, and are covered in the section below on the boot 75 command. If this is not specified, it is assumed the installer will start 76 itself. 77 78 * `boot_wait` (string) - The time to wait after booting the initial virtual 79 machine before typing the `boot_command`. The value of this should be 80 a duration. Examples are "5s" and "1m30s" which will cause Packer to wait 81 five seconds and one minute 30 seconds, respectively. If this isn't specified, 82 the default is 10 seconds. 83 84 * `export_opts` (array of strings) - Additional options to pass to the `VBoxManage export`. 85 This can be useful for passing product information to include in the resulting 86 appliance file. 87 88 * `floppy_files` (array of strings) - A list of files to place onto a floppy 89 disk that is attached when the VM is booted. This is most useful 90 for unattended Windows installs, which look for an `Autounattend.xml` file 91 on removable media. By default, no floppy will be attached. All files 92 listed in this setting get placed into the root directory of the floppy 93 and the floppy is attached as the first floppy device. Currently, no 94 support exists for creating sub-directories on the floppy. Wildcard 95 characters (*, ?, and []) are allowed. Directory names are also allowed, 96 which will add all the files found in the directory to the floppy. 97 98 * `format` (string) - Either "ovf" or "ova", this specifies the output 99 format of the exported virtual machine. This defaults to "ovf". 100 101 * `guest_additions_mode` (string) - The method by which guest additions 102 are made available to the guest for installation. Valid options are 103 "upload", "attach", or "disable". If the mode is "attach" the guest 104 additions ISO will be attached as a CD device to the virtual machine. 105 If the mode is "upload" the guest additions ISO will be uploaded to 106 the path specified by `guest_additions_path`. The default value is 107 "upload". If "disable" is used, guest additions won't be downloaded, 108 either. 109 110 * `guest_additions_path` (string) - The path on the guest virtual machine 111 where the VirtualBox guest additions ISO will be uploaded. By default this 112 is "VBoxGuestAdditions.iso" which should upload into the login directory 113 of the user. This is a [configuration template](/docs/templates/configuration-templates.html) 114 where the `Version` variable is replaced with the VirtualBox version. 115 116 * `guest_additions_sha256` (string) - The SHA256 checksum of the guest 117 additions ISO that will be uploaded to the guest VM. By default the 118 checksums will be downloaded from the VirtualBox website, so this only 119 needs to be set if you want to be explicit about the checksum. 120 121 * `guest_additions_url` (string) - The URL to the guest additions ISO 122 to upload. This can also be a file URL if the ISO is at a local path. 123 By default the VirtualBox builder will go and download the proper 124 guest additions ISO from the internet. 125 126 * `headless` (boolean) - Packer defaults to building VirtualBox 127 virtual machines by launching a GUI that shows the console of the 128 machine being built. When this value is set to true, the machine will 129 start without a console. 130 131 * `http_directory` (string) - Path to a directory to serve using an HTTP 132 server. The files in this directory will be available over HTTP that will 133 be requestable from the virtual machine. This is useful for hosting 134 kickstart files and so on. By default this is "", which means no HTTP 135 server will be started. The address and port of the HTTP server will be 136 available as variables in `boot_command`. This is covered in more detail 137 below. 138 139 * `http_port_min` and `http_port_max` (integer) - These are the minimum and 140 maximum port to use for the HTTP server started to serve the `http_directory`. 141 Because Packer often runs in parallel, Packer will choose a randomly available 142 port in this range to run the HTTP server. If you want to force the HTTP 143 server to be on one port, make this minimum and maximum port the same. 144 By default the values are 8000 and 9000, respectively. 145 146 * `import_flags` (array of strings) - Additional flags to pass to 147 `VBoxManage import`. This can be used to add additional command-line flags 148 such as `--eula-accept` to accept a EULA in the OVF. 149 150 * `import_opts` (string) - Additional options to pass to the `VBoxManage import`. 151 This can be useful for passing "keepallmacs" or "keepnatmacs" options for existing 152 ovf images. 153 154 * `output_directory` (string) - This is the path to the directory where the 155 resulting virtual machine will be created. This may be relative or absolute. 156 If relative, the path is relative to the working directory when `packer` 157 is executed. This directory must not exist or be empty prior to running the builder. 158 By default this is "output-BUILDNAME" where "BUILDNAME" is the name 159 of the build. 160 161 * `shutdown_command` (string) - The command to use to gracefully shut down the machine once all 162 the provisioning is done. By default this is an empty string, which tells Packer to just 163 forcefully shut down the machine unless a shutdown command takes place inside script so this may 164 safely be omitted. If one or more scripts require a reboot it is suggested to leave this blank 165 since reboots may fail and specify the final shutdown command in your last script. 166 167 * `shutdown_timeout` (string) - The amount of time to wait after executing 168 the `shutdown_command` for the virtual machine to actually shut down. 169 If it doesn't shut down in this time, it is an error. By default, the timeout 170 is "5m", or five minutes. 171 172 * `ssh_host_port_min` and `ssh_host_port_max` (integer) - The minimum and 173 maximum port to use for the SSH port on the host machine which is forwarded 174 to the SSH port on the guest machine. Because Packer often runs in parallel, 175 Packer will choose a randomly available port in this range to use as the 176 host port. 177 178 * `ssh_skip_nat_mapping` (bool) - Defaults to false. When enabled, Packer does 179 not setup forwarded port mapping for SSH requests and uses `ssh_port` on the 180 host to communicate to the virtual machine 181 182 * `vboxmanage` (array of array of strings) - Custom `VBoxManage` commands to 183 execute in order to further customize the virtual machine being created. 184 The value of this is an array of commands to execute. The commands are executed 185 in the order defined in the template. For each command, the command is 186 defined itself as an array of strings, where each string represents a single 187 argument on the command-line to `VBoxManage` (but excluding `VBoxManage` 188 itself). Each arg is treated as a [configuration template](/docs/templates/configuration-templates.html), 189 where the `Name` variable is replaced with the VM name. More details on how 190 to use `VBoxManage` are below. 191 192 * `vboxmanage_post` (array of array of strings) - Identical to `vboxmanage`, 193 except that it is run after the virtual machine is shutdown, and before the 194 virtual machine is exported. 195 196 * `virtualbox_version_file` (string) - The path within the virtual machine 197 to upload a file that contains the VirtualBox version that was used to 198 create the machine. This information can be useful for provisioning. 199 By default this is ".vbox_version", which will generally be upload it into 200 the home directory. 201 202 * `vm_name` (string) - This is the name of the virtual machine when it is 203 imported as well as the name of the OVF file when the virtual machine is 204 exported. By default this is "packer-BUILDNAME", where "BUILDNAME" is 205 the name of the build. 206 207 ## Guest Additions 208 209 Packer will automatically download the proper guest additions for the 210 version of VirtualBox that is running and upload those guest additions into 211 the virtual machine so that provisioners can easily install them. 212 213 Packer downloads the guest additions from the official VirtualBox website, 214 and verifies the file with the official checksums released by VirtualBox. 215 216 After the virtual machine is up and the operating system is installed, 217 Packer uploads the guest additions into the virtual machine. The path where 218 they are uploaded is controllable by `guest_additions_path`, and defaults 219 to "VBoxGuestAdditions.iso". Without an absolute path, it is uploaded to the 220 home directory of the SSH user. 221 222 ## VBoxManage Commands 223 224 In order to perform extra customization of the virtual machine, a template 225 can define extra calls to `VBoxManage` to perform. [VBoxManage](http://www.virtualbox.org/manual/ch08.html) 226 is the command-line interface to VirtualBox where you can completely control 227 VirtualBox. It can be used to do things such as set RAM, CPUs, etc. 228 229 Extra VBoxManage commands are defined in the template in the `vboxmanage` section. 230 An example is shown below that sets the memory and number of CPUs within the 231 virtual machine: 232 233 ```javascript 234 { 235 "vboxmanage": [ 236 ["modifyvm", "{{.Name}}", "--memory", "1024"], 237 ["modifyvm", "{{.Name}}", "--cpus", "2"] 238 ] 239 } 240 ``` 241 242 The value of `vboxmanage` is an array of commands to execute. These commands 243 are executed in the order defined. So in the above example, the memory will be 244 set followed by the CPUs. 245 246 Each command itself is an array of strings, where each string is an argument 247 to `VBoxManage`. Each argument is treated as a 248 [configuration template](/docs/templates/configuration-templates.html). 249 The only available variable is `Name` which is replaced with the unique 250 name of the VM, which is required for many VBoxManage calls.