github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/builders/qemu.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "QEMU Builder" 4 description: |- 5 The Qemu Packer builder is able to create KVM and Xen virtual machine images. Support for Xen is experimental at this time. 6 --- 7 8 # QEMU Builder 9 10 Type: `qemu` 11 12 The Qemu Packer builder is able to create [KVM](http://www.linux-kvm.org) 13 and [Xen](http://www.xenproject.org) virtual machine images. Support 14 for Xen is experimental at this time. 15 16 The builder builds a virtual machine by creating a new virtual machine 17 from scratch, booting it, installing an OS, rebooting the machine with the 18 boot media as the virtual hard drive, provisioning software within 19 the OS, then shutting it down. The result of the Qemu builder is a directory 20 containing the image file necessary to run the virtual machine on KVM or Xen. 21 22 ## Basic Example 23 24 Here is a basic example. This example is functional so long as you fixup 25 paths to files, URLS for ISOs and checksums. 26 27 ```javascript 28 { 29 "builders": 30 [ 31 { 32 "type": "qemu", 33 "iso_url": "http://mirror.raystedman.net/centos/6/isos/x86_64/CentOS-6.5-x86_64-minimal.iso", 34 "iso_checksum": "0d9dc37b5dd4befa1c440d2174e88a87", 35 "iso_checksum_type": "md5", 36 "output_directory": "output_centos_tdhtest", 37 "ssh_wait_timeout": "30s", 38 "shutdown_command": "shutdown -P now", 39 "disk_size": 5000, 40 "format": "qcow2", 41 "headless": false, 42 "accelerator": "kvm", 43 "http_directory": "httpdir", 44 "http_port_min": 10082, 45 "http_port_max": 10089, 46 "ssh_host_port_min": 2222, 47 "ssh_host_port_max": 2229, 48 "ssh_username": "root", 49 "ssh_password": "s0m3password", 50 "ssh_port": 22, 51 "ssh_wait_timeout": "90m", 52 "vm_name": "tdhtest", 53 "net_device": "virtio-net", 54 "disk_interface": "virtio", 55 "boot_wait": "5s", 56 "boot_command": 57 [ 58 "<tab> text ks=http://{{ .HTTPIP }}:{{ .HTTPPort }}/centos6-ks.cfg<enter><wait>" 59 ] 60 } 61 ] 62 } 63 ``` 64 65 A working CentOS 6.x kickstart file can be found 66 [at this URL](https://gist.github.com/mitchellh/7328271/#file-centos6-ks-cfg), adapted from an unknown source. 67 Place this file in the http directory with the proper name. For the 68 example above, it should go into "httpdir" with a name of "centos6-ks.cfg". 69 70 ## Configuration Reference 71 72 There are many configuration options available for the Qemu builder. 73 They are organized below into two categories: required and optional. Within 74 each category, the available options are alphabetized and described. 75 76 In addition to the options listed here, a 77 [communicator](/docs/templates/communicator.html) 78 can be configured for this builder. 79 80 ### Required: 81 82 * `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO 83 files are so large, this is required and Packer will verify it prior 84 to booting a virtual machine with the ISO attached. The type of the 85 checksum is specified with `iso_checksum_type`, documented below. 86 87 * `iso_checksum_type` (string) - The type of the checksum specified in 88 `iso_checksum`. Valid values are "md5", "sha1", "sha256", or "sha512" currently. 89 90 * `iso_url` (string) - A URL to the ISO containing the installation image. 91 This URL can be either an HTTP URL or a file URL (or path to a file). 92 If this is an HTTP URL, Packer will download it and cache it between 93 runs. 94 95 * `ssh_username` (string) - The username to use to SSH into the machine 96 once the OS is installed. 97 98 ### Optional: 99 100 * `accelerator` (string) - The accelerator type to use when running the VM. 101 This may have a value of either "none", "kvm", "tcg", or "xen" and you must have that 102 support in on the machine on which you run the builder. By default "kvm" 103 is used. 104 105 * `boot_command` (array of strings) - This is an array of commands to type 106 when the virtual machine is first booted. The goal of these commands should 107 be to type just enough to initialize the operating system installer. Special 108 keys can be typed as well, and are covered in the section below on the boot 109 command. If this is not specified, it is assumed the installer will start 110 itself. 111 112 * `boot_wait` (string) - The time to wait after booting the initial virtual 113 machine before typing the `boot_command`. The value of this should be 114 a duration. Examples are "5s" and "1m30s" which will cause Packer to wait 115 five seconds and one minute 30 seconds, respectively. If this isn't specified, 116 the default is 10 seconds. 117 118 * `disk_cache` (string) - The cache mode to use for disk. Allowed values 119 values include any of "writethrough", "writeback", "none", "unsafe" or 120 "directsync". 121 122 * `disk_discard` (string) - The discard mode to use for disk. Allowed values 123 include any of "unmap" or "ignore". 124 125 * `disk_image` (boolean) - Packer defaults to building from an ISO file, 126 this parameter controls whether the ISO URL supplied is actually a bootable 127 QEMU image. When this value is set to true, the machine will clone the 128 source, resize it according to `disk_size` and boot the image. 129 130 * `disk_interface` (string) - The interface to use for the disk. Allowed 131 values include any of "ide," "scsi" or "virtio." Note also that any boot 132 commands or kickstart type scripts must have proper adjustments for 133 resulting device names. The Qemu builder uses "virtio" by default. 134 135 * `disk_size` (integer) - The size, in megabytes, of the hard disk to create 136 for the VM. By default, this is 40000 (about 40 GB). 137 138 * `floppy_files` (array of strings) - A list of files to place onto a floppy 139 disk that is attached when the VM is booted. This is most useful 140 for unattended Windows installs, which look for an `Autounattend.xml` file 141 on removable media. By default, no floppy will be attached. All files 142 listed in this setting get placed into the root directory of the floppy 143 and the floppy is attached as the first floppy device. Currently, no 144 support exists for creating sub-directories on the floppy. Wildcard 145 characters (*, ?, and []) are allowed. Directory names are also allowed, 146 which will add all the files found in the directory to the floppy. 147 148 * `format` (string) - Either "qcow2" or "raw", this specifies the output 149 format of the virtual machine image. This defaults to "qcow2". 150 151 * `headless` (boolean) - Packer defaults to building virtual machines by 152 launching a GUI that shows the console of the machine being built. 153 When this value is set to true, the machine will start without a console. 154 155 * `http_directory` (string) - Path to a directory to serve using an HTTP 156 server. The files in this directory will be available over HTTP that will 157 be requestable from the virtual machine. This is useful for hosting 158 kickstart files and so on. By default this is "", which means no HTTP 159 server will be started. The address and port of the HTTP server will be 160 available as variables in `boot_command`. This is covered in more detail 161 below. 162 163 * `http_port_min` and `http_port_max` (integer) - These are the minimum and 164 maximum port to use for the HTTP server started to serve the `http_directory`. 165 Because Packer often runs in parallel, Packer will choose a randomly available 166 port in this range to run the HTTP server. If you want to force the HTTP 167 server to be on one port, make this minimum and maximum port the same. 168 By default the values are 8000 and 9000, respectively. 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 download 172 or while downloading a single URL, it will move on to the next. All URLs 173 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 * `machine_type` (string) - The type of machine emulation to use. Run 177 your qemu binary with the flags `-machine help` to list available types 178 for your system. This defaults to "pc". 179 180 * `net_device` (string) - The driver to use for the network interface. Allowed 181 values "ne2k_pci," "i82551," "i82557b," "i82559er," "rtl8139," "e1000," 182 "pcnet" or "virtio." The Qemu builder uses "virtio" by default. 183 184 * `output_directory` (string) - This is the path to the directory where the 185 resulting virtual machine will be created. This may be relative or absolute. 186 If relative, the path is relative to the working directory when `packer` 187 is executed. This directory must not exist or be empty prior to running the builder. 188 By default this is "output-BUILDNAME" where "BUILDNAME" is the name 189 of the build. 190 191 * `qemuargs` (array of array of strings) - Allows complete control over 192 the qemu command line (though not, at this time, qemu-img). Each array 193 of strings makes up a command line switch that overrides matching default 194 switch/value pairs. Any value specified as an empty string is ignored. 195 All values after the switch are concatenated with no separator. 196 197 ~> **Warning:** The qemu command line allows extreme flexibility, so beware of 198 conflicting arguments causing failures of your run. For instance, using 199 --no-acpi could break the ability to send power signal type commands (e.g., 200 shutdown -P now) to the virtual machine, thus preventing proper shutdown. To 201 see the defaults, look in the packer.log file and search for the 202 qemu-system-x86 command. The arguments are all printed for review. 203 204 The following shows a sample usage: 205 206 ```javascript 207 // ... 208 "qemuargs": [ 209 [ "-m", "1024M" ], 210 [ "--no-acpi", "" ], 211 [ 212 "-netdev", 213 "user,id=mynet0,", 214 "hostfwd=hostip:hostport-guestip:guestport", 215 "" 216 ], 217 [ "-device", "virtio-net,netdev=mynet0" ] 218 ] 219 // ... 220 ``` 221 222 would produce the following (not including other defaults supplied by the builder and not otherwise conflicting with the qemuargs): 223 224 <pre class="prettyprint"> 225 qemu-system-x86 -m 1024m --no-acpi -netdev user,id=mynet0,hostfwd=hostip:hostport-guestip:guestport -device virtio-net,netdev=mynet0" 226 </pre> 227 228 * `qemu_binary` (string) - The name of the Qemu binary to look for. This 229 defaults to "qemu-system-x86_64", but may need to be changed for some 230 platforms. For example "qemu-kvm", or "qemu-system-i386" may be a better 231 choice for some systems. 232 233 * `shutdown_command` (string) - The command to use to gracefully shut down 234 the machine once all the provisioning is done. By default this is an empty 235 string, which tells Packer to just forcefully shut down the machine. 236 237 * `shutdown_timeout` (string) - The amount of time to wait after executing 238 the `shutdown_command` for the virtual machine to actually shut down. 239 If it doesn't shut down in this time, it is an error. By default, the timeout 240 is "5m", or five minutes. 241 242 * `ssh_host_port_min` and `ssh_host_port_max` (uint) - The minimum and 243 maximum port to use for the SSH port on the host machine which is forwarded 244 to the SSH port on the guest machine. Because Packer often runs in parallel, 245 Packer will choose a randomly available port in this range to use as the 246 host port. 247 248 * `vm_name` (string) - This is the name of the image (QCOW2 or IMG) file for 249 the new virtual machine, without the file extension. By default this is 250 "packer-BUILDNAME", where "BUILDNAME" is the name of the build. 251 252 * `vnc_port_min` and `vnc_port_max` (integer) - The minimum and 253 maximum port to use for the VNC port on the host machine which is forwarded 254 to the VNC port on the guest machine. Because Packer often runs in parallel, 255 Packer will choose a randomly available port in this range to use as the 256 host port. 257 258 ## Boot Command 259 260 The `boot_command` configuration is very important: it specifies the keys 261 to type when the virtual machine is first booted in order to start the 262 OS installer. This command is typed after `boot_wait`, which gives the 263 virtual machine some time to actually load the ISO. 264 265 As documented above, the `boot_command` is an array of strings. The 266 strings are all typed in sequence. It is an array only to improve readability 267 within the template. 268 269 The boot command is "typed" character for character over a VNC connection 270 to the machine, simulating a human actually typing the keyboard. There are 271 a set of special keys available. If these are in your boot command, they 272 will be replaced by the proper key: 273 274 * `<bs>` - Backspace 275 276 * `<del>` - Delete 277 278 * `<enter>` and `<return>` - Simulates an actual "enter" or "return" keypress. 279 280 * `<esc>` - Simulates pressing the escape key. 281 282 * `<tab>` - Simulates pressing the tab key. 283 284 * `<f1>` - `<f12>` - Simulates pressing a function key. 285 286 * `<up>` `<down>` `<left>` `<right>` - Simulates pressing an arrow key. 287 288 * `<spacebar>` - Simulates pressing the spacebar. 289 290 * `<insert>` - Simulates pressing the insert key. 291 292 * `<home>` `<end>` - Simulates pressing the home and end keys. 293 294 * `<pageUp>` `<pageDown>` - Simulates pressing the page up and page down keys. 295 296 * `<wait>` `<wait5>` `<wait10>` - Adds a 1, 5 or 10 second pause before sending any additional keys. This 297 is useful if you have to generally wait for the UI to update before typing more. 298 299 In addition to the special keys, each command to type is treated as a 300 [configuration template](/docs/templates/configuration-templates.html). 301 The available variables are: 302 303 * `HTTPIP` and `HTTPPort` - The IP and port, respectively of an HTTP server 304 that is started serving the directory specified by the `http_directory` 305 configuration parameter. If `http_directory` isn't specified, these will 306 be blank! 307 308 Example boot command. This is actually a working boot command used to start 309 an CentOS 6.4 installer: 310 311 ```javascript 312 "boot_command": 313 [ 314 "<tab><wait>", 315 " ks=http://10.0.2.2:{{ .HTTPPort }}/centos6-ks.cfg<enter>" 316 ] 317 ```